@dreamtree-org/twreact-ui 1.1.64 → 1.1.65

package/dist/components/core/Select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Select.d.ts","sourceRoot":"","sources":["../../../src/components/core/Select.jsx"],"names":[],"mappings":";AAiDA,gFA6kBE;kBAxnBK,OAAO"}
+{"version":3,"file":"Select.d.ts","sourceRoot":"","sources":["../../../src/components/core/Select.jsx"],"names":[],"mappings":";AAmDA,gFA+nBE;kBA3qBK,OAAO"}

package/dist/index.esm.js

@@ -3490,6 +3490,11 @@ var Select = /*#__PURE__*/React__default.forwardRef(function (_ref, forwardedRef
     _useState10 = _slicedToArray(_useState1, 2),
     menuMaxHeight = _useState10[0],
     setMenuMaxHeight = _useState10[1]; // px or null
+  // Fixed-position coordinates for the portaled menu (anchored to the trigger).
+  var _useState11 = useState(null),
+    _useState12 = _slicedToArray(_useState11, 2),
+    menuCoords = _useState12[0],
+    setMenuCoords = _useState12[1]; // { left, top, width } in viewport px
   useImperativeHandle(forwardedRef, function () {
     return selectRef.current;
   }, []);
@@ -3552,16 +3557,47 @@ var Select = /*#__PURE__*/React__default.forwardRef(function (_ref, forwardedRef
       desiredMenuHeight = Math.min(menuRef.current.scrollHeight, DEFAULT_MENU_MAX);
     }
     // decide placement: prefer bottom unless not enough space and top has more space
+    var nextPlacement;
+    var nextMaxHeight;
     if (spaceBelow >= desiredMenuHeight || spaceBelow >= spaceAbove) {
-      setPlacement("bottom");
-      setMenuMaxHeight(Math.min(desiredMenuHeight, Math.max(80, spaceBelow)));
+      nextPlacement = "bottom";
+      nextMaxHeight = Math.min(desiredMenuHeight, Math.max(80, spaceBelow));
+    } else {
+      nextPlacement = "top";
+      nextMaxHeight = Math.min(desiredMenuHeight, Math.max(80, spaceAbove));
+    }
+    setPlacement(nextPlacement);
+    setMenuMaxHeight(nextMaxHeight);
+    // The menu is portaled to document.body with position:fixed, so it floats
+    // above any ancestor with overflow:hidden|auto|scroll. Anchor it to the
+    // trigger via the viewport-relative rect (no scroll offset for fixed).
+    // maxHeight here mirrors the inline style applied to the menu (+10 fudge).
+    var renderedMaxHeight = nextMaxHeight + 10;
+    var next = {
+      left: rect.left,
+      width: rect.width
+    };
+    if (nextPlacement === "bottom") {
+      next.top = rect.bottom + 4; // ~mt-1
     } else {
-      setPlacement("top");
-      setMenuMaxHeight(Math.min(desiredMenuHeight, Math.max(80, spaceAbove)));
+      // place above the trigger; bottom of menu sits just above the trigger top
+      next.top = Math.max(MARGIN, rect.top - 4 - renderedMaxHeight);
     }
+    setMenuCoords(next);
   };
+  // Anchor the portaled menu BEFORE the browser paints, so it never flashes
+  // at (0,0). The menu is already in the DOM (createPortal runs during render),
+  // we just need its fixed coords set synchronously.
+  useLayoutEffect(function () {
+    if (isOpen) calculatePlacement();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen, filtered.length]);
   useEffect(function () {
-    if (!isOpen) return;
+    if (!isOpen) {
+      // drop stale coords so the next open re-anchors from scratch
+      setMenuCoords(null);
+      return;
+    }
     // initial calc on open; wait a tick to allow DOM to render
     var raf = requestAnimationFrame(function () {
       var _searchRef$current;
@@ -3569,7 +3605,10 @@ var Select = /*#__PURE__*/React__default.forwardRef(function (_ref, forwardedRef
       // focus search input if available
       if (searchable) (_searchRef$current = searchRef.current) === null || _searchRef$current === void 0 || _searchRef$current.focus();
     });
-    // update on resize/scroll (throttle by requestAnimationFrame)
+    // Reposition on resize/scroll while open (throttled by rAF). Use
+    // capture-phase scroll so we also catch any scrolling ancestor — the
+    // menu is portaled with position:fixed, so its coords must track the
+    // trigger as the page (or a scroll container) moves.
     var rafId = null;
     var onWindowChange = function onWindowChange() {
       if (rafId) cancelAnimationFrame(rafId);
@@ -3581,13 +3620,16 @@ var Select = /*#__PURE__*/React__default.forwardRef(function (_ref, forwardedRef
       passive: true
     });
     window.addEventListener("scroll", onWindowChange, {
-      passive: true
+      passive: true,
+      capture: true
     });
     return function () {
       cancelAnimationFrame(raf);
       if (rafId) cancelAnimationFrame(rafId);
       window.removeEventListener("resize", onWindowChange);
-      window.removeEventListener("scroll", onWindowChange);
+      window.removeEventListener("scroll", onWindowChange, {
+        capture: true
+      });
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isOpen, searchable, filtered.length]);
@@ -3677,7 +3719,13 @@ var Select = /*#__PURE__*/React__default.forwardRef(function (_ref, forwardedRef
     }
   };
   var handleClickOutside = function handleClickOutside(e) {
-    if (selectRef.current && !selectRef.current.contains(e.target)) {
+    // The menu is portaled to document.body, so it lives OUTSIDE selectRef's
+    // DOM subtree. Treat clicks inside the portaled menu as "inside" too —
+    // otherwise selecting an option would close the menu before the option's
+    // own click handler runs.
+    var inTrigger = selectRef.current && selectRef.current.contains(e.target);
+    var inMenu = menuRef.current && menuRef.current.contains(e.target);
+    if (!inTrigger && !inMenu) {
       setIsOpen(false);
       setFocusedIndex(-1);
     }
@@ -3901,19 +3949,23 @@ var Select = /*#__PURE__*/React__default.forwardRef(function (_ref, forwardedRef
         type: "hidden",
         name: name,
         value: selectedValues !== null && selectedValues !== void 0 ? selectedValues : ""
-      })), isOpen && jsxs("div", {
+      })), isOpen && typeof document !== "undefined" && /*#__PURE__*/createPortal(jsxs("div", {
         ref: menuRef,
-        className: cn$1("absolute z-50 w-full rounded-md border border-gray-300 bg-white shadow-lg", {
-          // if placement is bottom, place it below with margin-top; if top, place it above with bottom full and margin-bottom
-          "mt-1 top-full": placement === "bottom",
-          "mb-1 bottom-full": placement === "top"
-        }),
+        className: cn$1("fixed z-50 rounded-md border border-gray-300 bg-white shadow-lg"),
         role: "dialog",
-        // set inline style for maxHeight based on available space (converted to px)
-        style: menuMaxHeight ? {
+        "data-placement": placement,
+        // Portaled to document.body with position:fixed so the menu
+        // escapes any ancestor overflow:hidden|auto|scroll. Coordinates
+        // are anchored to the trigger's viewport rect; width matches the
+        // trigger; maxHeight is driven by available space.
+        style: _objectSpread$C({
+          left: menuCoords ? "".concat(menuCoords.left, "px") : undefined,
+          top: menuCoords ? "".concat(menuCoords.top, "px") : undefined,
+          width: menuCoords ? "".concat(menuCoords.width, "px") : undefined
+        }, menuMaxHeight ? {
           maxHeight: "".concat(menuMaxHeight + 10, "px"),
           overflow: "auto"
-        } : {},
+        } : {}),
         children: [searchable && jsx("div", {
           className: "border-b border-gray-200 p-2",
           children: jsxs("div", {
@@ -3956,7 +4008,7 @@ var Select = /*#__PURE__*/React__default.forwardRef(function (_ref, forwardedRef
           "aria-multiselectable": multiSelect,
           children: grouped ? renderGroupedOptions() : renderFlatOptions()
         })]
-      })]
+      }), document.body)]
     }), error && jsx("p", {
       className: "mt-1 text-sm text-error-500",
       children: error

package/dist/index.js

@@ -3510,6 +3510,11 @@ var Select = /*#__PURE__*/React.forwardRef(function (_ref, forwardedRef) {
     _useState10 = _slicedToArray(_useState1, 2),
     menuMaxHeight = _useState10[0],
     setMenuMaxHeight = _useState10[1]; // px or null
+  // Fixed-position coordinates for the portaled menu (anchored to the trigger).
+  var _useState11 = React.useState(null),
+    _useState12 = _slicedToArray(_useState11, 2),
+    menuCoords = _useState12[0],
+    setMenuCoords = _useState12[1]; // { left, top, width } in viewport px
   React.useImperativeHandle(forwardedRef, function () {
     return selectRef.current;
   }, []);
@@ -3572,16 +3577,47 @@ var Select = /*#__PURE__*/React.forwardRef(function (_ref, forwardedRef) {
       desiredMenuHeight = Math.min(menuRef.current.scrollHeight, DEFAULT_MENU_MAX);
     }
     // decide placement: prefer bottom unless not enough space and top has more space
+    var nextPlacement;
+    var nextMaxHeight;
     if (spaceBelow >= desiredMenuHeight || spaceBelow >= spaceAbove) {
-      setPlacement("bottom");
-      setMenuMaxHeight(Math.min(desiredMenuHeight, Math.max(80, spaceBelow)));
+      nextPlacement = "bottom";
+      nextMaxHeight = Math.min(desiredMenuHeight, Math.max(80, spaceBelow));
+    } else {
+      nextPlacement = "top";
+      nextMaxHeight = Math.min(desiredMenuHeight, Math.max(80, spaceAbove));
+    }
+    setPlacement(nextPlacement);
+    setMenuMaxHeight(nextMaxHeight);
+    // The menu is portaled to document.body with position:fixed, so it floats
+    // above any ancestor with overflow:hidden|auto|scroll. Anchor it to the
+    // trigger via the viewport-relative rect (no scroll offset for fixed).
+    // maxHeight here mirrors the inline style applied to the menu (+10 fudge).
+    var renderedMaxHeight = nextMaxHeight + 10;
+    var next = {
+      left: rect.left,
+      width: rect.width
+    };
+    if (nextPlacement === "bottom") {
+      next.top = rect.bottom + 4; // ~mt-1
     } else {
-      setPlacement("top");
-      setMenuMaxHeight(Math.min(desiredMenuHeight, Math.max(80, spaceAbove)));
+      // place above the trigger; bottom of menu sits just above the trigger top
+      next.top = Math.max(MARGIN, rect.top - 4 - renderedMaxHeight);
     }
+    setMenuCoords(next);
   };
+  // Anchor the portaled menu BEFORE the browser paints, so it never flashes
+  // at (0,0). The menu is already in the DOM (createPortal runs during render),
+  // we just need its fixed coords set synchronously.
+  React.useLayoutEffect(function () {
+    if (isOpen) calculatePlacement();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen, filtered.length]);
   React.useEffect(function () {
-    if (!isOpen) return;
+    if (!isOpen) {
+      // drop stale coords so the next open re-anchors from scratch
+      setMenuCoords(null);
+      return;
+    }
     // initial calc on open; wait a tick to allow DOM to render
     var raf = requestAnimationFrame(function () {
       var _searchRef$current;
@@ -3589,7 +3625,10 @@ var Select = /*#__PURE__*/React.forwardRef(function (_ref, forwardedRef) {
       // focus search input if available
       if (searchable) (_searchRef$current = searchRef.current) === null || _searchRef$current === void 0 || _searchRef$current.focus();
     });
-    // update on resize/scroll (throttle by requestAnimationFrame)
+    // Reposition on resize/scroll while open (throttled by rAF). Use
+    // capture-phase scroll so we also catch any scrolling ancestor — the
+    // menu is portaled with position:fixed, so its coords must track the
+    // trigger as the page (or a scroll container) moves.
     var rafId = null;
     var onWindowChange = function onWindowChange() {
       if (rafId) cancelAnimationFrame(rafId);
@@ -3601,13 +3640,16 @@ var Select = /*#__PURE__*/React.forwardRef(function (_ref, forwardedRef) {
       passive: true
     });
     window.addEventListener("scroll", onWindowChange, {
-      passive: true
+      passive: true,
+      capture: true
     });
     return function () {
       cancelAnimationFrame(raf);
       if (rafId) cancelAnimationFrame(rafId);
       window.removeEventListener("resize", onWindowChange);
-      window.removeEventListener("scroll", onWindowChange);
+      window.removeEventListener("scroll", onWindowChange, {
+        capture: true
+      });
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isOpen, searchable, filtered.length]);
@@ -3697,7 +3739,13 @@ var Select = /*#__PURE__*/React.forwardRef(function (_ref, forwardedRef) {
     }
   };
   var handleClickOutside = function handleClickOutside(e) {
-    if (selectRef.current && !selectRef.current.contains(e.target)) {
+    // The menu is portaled to document.body, so it lives OUTSIDE selectRef's
+    // DOM subtree. Treat clicks inside the portaled menu as "inside" too —
+    // otherwise selecting an option would close the menu before the option's
+    // own click handler runs.
+    var inTrigger = selectRef.current && selectRef.current.contains(e.target);
+    var inMenu = menuRef.current && menuRef.current.contains(e.target);
+    if (!inTrigger && !inMenu) {
       setIsOpen(false);
       setFocusedIndex(-1);
     }
@@ -3921,19 +3969,23 @@ var Select = /*#__PURE__*/React.forwardRef(function (_ref, forwardedRef) {
         type: "hidden",
         name: name,
         value: selectedValues !== null && selectedValues !== void 0 ? selectedValues : ""
-      })), isOpen && jsxRuntime.jsxs("div", {
+      })), isOpen && typeof document !== "undefined" && /*#__PURE__*/ReactDOM.createPortal(jsxRuntime.jsxs("div", {
         ref: menuRef,
-        className: cn$1("absolute z-50 w-full rounded-md border border-gray-300 bg-white shadow-lg", {
-          // if placement is bottom, place it below with margin-top; if top, place it above with bottom full and margin-bottom
-          "mt-1 top-full": placement === "bottom",
-          "mb-1 bottom-full": placement === "top"
-        }),
+        className: cn$1("fixed z-50 rounded-md border border-gray-300 bg-white shadow-lg"),
         role: "dialog",
-        // set inline style for maxHeight based on available space (converted to px)
-        style: menuMaxHeight ? {
+        "data-placement": placement,
+        // Portaled to document.body with position:fixed so the menu
+        // escapes any ancestor overflow:hidden|auto|scroll. Coordinates
+        // are anchored to the trigger's viewport rect; width matches the
+        // trigger; maxHeight is driven by available space.
+        style: _objectSpread$C({
+          left: menuCoords ? "".concat(menuCoords.left, "px") : undefined,
+          top: menuCoords ? "".concat(menuCoords.top, "px") : undefined,
+          width: menuCoords ? "".concat(menuCoords.width, "px") : undefined
+        }, menuMaxHeight ? {
           maxHeight: "".concat(menuMaxHeight + 10, "px"),
           overflow: "auto"
-        } : {},
+        } : {}),
         children: [searchable && jsxRuntime.jsx("div", {
           className: "border-b border-gray-200 p-2",
           children: jsxRuntime.jsxs("div", {
@@ -3976,7 +4028,7 @@ var Select = /*#__PURE__*/React.forwardRef(function (_ref, forwardedRef) {
           "aria-multiselectable": multiSelect,
           children: grouped ? renderGroupedOptions() : renderFlatOptions()
         })]
-      })]
+      }), document.body)]
     }), error && jsxRuntime.jsx("p", {
       className: "mt-1 text-sm text-error-500",
       children: error

package/mcp/catalog.snapshot.json

@@ -3155,7 +3155,7 @@
     "Radio": "# Radio\n\nSingle radio button; use multiple with the same `name` for a group. Controlled via `checked` or uncontrolled via `defaultChecked`.\n\n## Import\n\n```jsx\nimport { Radio } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `id` | `string` | auto | Input id. |\n| `name` | `string` | — | Group name (required for grouping). |\n| `value` | `any` | — | Value when selected. |\n| `checked` | `boolean` | — | Controlled checked. |\n| `defaultChecked` | `boolean` | — | Uncontrolled initial. |\n| `onChange` | `(e: Event) => void` | — | Change handler. |\n| `disabled` | `boolean` | `false` | Disable. |\n| `required` | `boolean` | `false` | Required. |\n| `label` | `string` | — | Label text. |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `\"md\"` | Size. |\n| `labelPosition` | `\"left\"` \\| `\"right\"` | `\"right\"` | Label side. |\n| `radioColor` | `string` | `\"blue\"` | Accent color (Tailwind name). |\n| `className` | `string` | `\"\"` | Label wrapper classes. |\n| `ariaLabel` | `string` | — | Accessibility label. |\n\n## Example\n\n```jsx\nconst [choice, setChoice] = useState('a');\n<>\n  <Radio name=\"choice\" value=\"a\" checked={choice === 'a'} onChange={() => setChoice('a')} label=\"Option A\" />\n  <Radio name=\"choice\" value=\"b\" checked={choice === 'b'} onChange={() => setChoice('b')} label=\"Option B\" />\n</>\n```\n\n[← Component overview](README.md)\n",
     "Rate": "# Rate\n\nStar (or custom icon) rating input/display. Controlled via `value` or uncontrolled via `defaultValue`. Supports hover preview and optional read-only.\n\n## Import\n\n```jsx\nimport { Rate } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `count` | `number` | `5` | Number of stars. |\n| `value` | `number` | — | Controlled value (0 to count). |\n| `defaultValue` | `number` | `0` | Uncontrolled initial value. |\n| `readOnly` | `boolean` | `false` | Read-only (no onChange). |\n| `icon` | `ReactNode` | `<StarOutline />` | Icon for inactive star. |\n| `toggledIcon` | `ReactNode` | `<StarFilled />` | Icon for active star. |\n| `activeColor` | `string` | `\"#f6b026\"` | Color for active stars. |\n| `inactiveColor` | `string` | `\"#e5e7eb\"` | Color for inactive stars. |\n| `size` | `number` | `20` | Icon size in px. |\n| `onChange` | `(value: number) => void` | — | Called when value changes. |\n| `onClick` | `(value: number) => void` | — | Called on star click. |\n| `text` | `ReactNode` | — | Optional text (e.g. label) next to stars. |\n| `className` | `string` | `\"\"` | Wrapper CSS classes. |\n| `id` | `string` | — | Wrapper id. |\n| `name` | `string` | — | Form field name. |\n\n## Example\n\n```jsx\nconst [rating, setRating] = useState(0);\n<Rate value={rating} onChange={setRating} count={5} />\n<Rate defaultValue={3} readOnly />\n```\n\n[← Component overview](README.md)\n",
     "RoundedTag": "# RoundedTag\n\nTag/chip with optional avatar (image or initials) and optional remove button. Used for labels, selected items, or filters.\n\n## Import\n\n```jsx\nimport { RoundedTag } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `label` | `string` | — | Main label text. |\n| `avatarSrc` | `string` | `null` | Image URL for avatar. |\n| `avatarAlt` | `string` | `\"avatar\"` | Alt for avatar image. |\n| `initials` | `string` | `\"\"` | Initials when no image (e.g. \"AB\"). |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `\"md\"` | Size. |\n| `onRemove` | `(e?) => void` | `null` | If provided, shows remove button and calls on click. |\n| `onClick` | `(e?) => void` | `null` | Click handler for the tag. |\n| `className` | `string` | `\"\"` | Wrapper CSS classes. |\n| `closeClass` | `string` | `\"\"` | Remove button CSS classes. |\n| `ariaLabel` | `string` | `\"tag\"` | Accessibility label. |\n| `avatarPosition` | `\"left\"` \\| `\"right\"` | `\"left\"` | Avatar position. |\n| `avatarClassname` | `string` | `\"\"` | Avatar wrapper classes. |\n| `initialClassname` | `string` | `\"\"` | Initials span classes. |\n\n## Example\n\n```jsx\n<RoundedTag label=\"React\" />\n<RoundedTag label=\"John\" initials=\"JD\" onRemove={() => {}} />\n<RoundedTag label=\"With image\" avatarSrc=\"/user.jpg\" size=\"lg\" />\n```\n\n[← Component overview](README.md)\n",
-    "Select": "# Select\n\nSingle or multi-select dropdown with search, grouped options, creatable options, and optional select-all.\n\n## Import\n\n```jsx\nimport { Select } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `options` | `Array` | `[]` | `[{ value, label, disabled }]` or grouped `[{ label, options: [...] }]` |\n| `value` | `any` \\| `any[]` | — | Selected value(s); array when `multiSelect` |\n| `onChange` | `function` | — | `(value)` or `(values[])` |\n| `placeholder` | `string` | `\"Select an option...\"` | Placeholder text |\n| `label` | `string` | — | Label |\n| `error` | `string` | — | Error message |\n| `disabled` | `boolean` | — | Disable select |\n| `required` | `boolean` | — | Required |\n| `multiSelect` | `boolean` | `false` | Allow multiple selection |\n| `searchable` | `boolean` | `false` | Show search input |\n| `grouped` | `boolean` | `false` | Options are grouped |\n| `allowClear` | `boolean` | `true` | Show clear button |\n| `creatable` | `boolean` | `false` | Allow creating new option when no match |\n| `onCreateOption` | `function` | — | Called when creating option |\n| `onSearch` | `function` | — | Search term callback |\n| `loading` | `boolean` | `false` | Loading state |\n| `selectAllOption` | `boolean` | `true` | Show select all (multi) |\n| `closeOnSelect` | `boolean` | `false` | Close dropdown on select (single) |\n| `maxTagCount` | `number` | `3` | Max tags shown in multi (rest as \"+N\") |\n| `onMenuItemRender` | `function` | — | Custom option render |\n| `renderGroupLabel` | `function` | — | Custom group label |\n| `name` | `string` | — | Form field name |\n| `className` | `string` | — | Extra CSS classes |\n\n## Examples\n\n### Basic single select\n\n```jsx\nconst options = [\n  { value: 'a', label: 'Option A' },\n  { value: 'b', label: 'Option B' },\n];\n<Select\n  options={options}\n  value={value}\n  onChange={setValue}\n  placeholder=\"Choose one\"\n/>\n```\n\n### Multi select with search\n\n```jsx\n<Select\n  options={options}\n  value={selected}\n  onChange={setSelected}\n  multiSelect\n  searchable\n  placeholder=\"Choose multiple\"\n/>\n```\n\n### Grouped options\n\n```jsx\nconst grouped = [\n  { label: 'Fruits', options: [{ value: 'apple', label: 'Apple' }, { value: 'banana', label: 'Banana' }] },\n  { label: 'Veggies', options: [{ value: 'carrot', label: 'Carrot' }] },\n];\n<Select options={grouped} grouped value={value} onChange={setValue} />\n```\n\n[← Component overview](README.md)\n",
+    "Select": "# Select\n\nSingle or multi-select dropdown with search, grouped options, creatable options, and optional select-all.\n\n> **The open menu portals to `document.body`.** The dropdown is rendered through\n> a React portal with `position: fixed`, anchored to the trigger via its viewport\n> rect. This means the menu **escapes any ancestor with `overflow: hidden | auto |\n> scroll`** instead of being clipped by it, and it repositions on scroll/resize\n> while open. There is no new prop and no opt-out — portaling is the default\n> behavior. Behaviorally everything else is unchanged (keyboard nav,\n> click-outside-to-close, placement flip, trigger-width matching, ARIA wiring).\n\n## Import\n\n```jsx\nimport { Select } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `options` | `Array` | `[]` | `[{ value, label, disabled }]` or grouped `[{ label, options: [...] }]` |\n| `value` | `any` \\| `any[]` | — | Selected value(s); array when `multiSelect` |\n| `onChange` | `function` | — | `(value)` or `(values[])` |\n| `placeholder` | `string` | `\"Select an option...\"` | Placeholder text |\n| `label` | `string` | — | Label |\n| `error` | `string` | — | Error message |\n| `disabled` | `boolean` | — | Disable select |\n| `required` | `boolean` | — | Required |\n| `multiSelect` | `boolean` | `false` | Allow multiple selection |\n| `searchable` | `boolean` | `false` | Show search input |\n| `grouped` | `boolean` | `false` | Options are grouped |\n| `allowClear` | `boolean` | `true` | Show clear button |\n| `creatable` | `boolean` | `false` | Allow creating new option when no match |\n| `onCreateOption` | `function` | — | Called when creating option |\n| `onSearch` | `function` | — | Search term callback |\n| `loading` | `boolean` | `false` | Loading state |\n| `selectAllOption` | `boolean` | `true` | Show select all (multi) |\n| `closeOnSelect` | `boolean` | `false` | Close dropdown on select (single) |\n| `maxTagCount` | `number` | `3` | Max tags shown in multi (rest as \"+N\") |\n| `onMenuItemRender` | `function` | — | Custom option render |\n| `renderGroupLabel` | `function` | — | Custom group label |\n| `name` | `string` | — | Form field name |\n| `className` | `string` | — | Extra CSS classes |\n\n## Examples\n\n### Basic single select\n\n```jsx\nconst options = [\n  { value: 'a', label: 'Option A' },\n  { value: 'b', label: 'Option B' },\n];\n<Select\n  options={options}\n  value={value}\n  onChange={setValue}\n  placeholder=\"Choose one\"\n/>\n```\n\n### Multi select with search\n\n```jsx\n<Select\n  options={options}\n  value={selected}\n  onChange={setSelected}\n  multiSelect\n  searchable\n  placeholder=\"Choose multiple\"\n/>\n```\n\n### Grouped options\n\n```jsx\nconst grouped = [\n  { label: 'Fruits', options: [{ value: 'apple', label: 'Apple' }, { value: 'banana', label: 'Banana' }] },\n  { label: 'Veggies', options: [{ value: 'carrot', label: 'Carrot' }] },\n];\n<Select options={grouped} grouped value={value} onChange={setValue} />\n```\n\n[← Component overview](README.md)\n",
     "Sidebar": "# Sidebar\n\nCollapsible side navigation with optional nested items, logo, and user block. Supports desktop collapsed state and mobile drawer. Tooltips show when collapsed; optional `drawerPosition` for mobile.\n\n## Import\n\n```jsx\nimport { Sidebar } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `Array` | `[]` | Nav items: `{ id, label, icon, children?, onClick?, active? }`. `children` = nested items. |\n| `collapsed` | `boolean` | `false` | Desktop collapsed state (icon-only). |\n| `onToggle` | `() => void` | — | Toggle collapse (e.g. chevron click). |\n| `className` | `string` | — | Wrapper CSS classes. |\n| `logo` | `ReactNode` | — | Logo at top. |\n| `user` | `object` \\| `ReactNode` | — | User block at bottom. |\n| `onUserClick` | `function` | — | User block click. |\n| `drawerPosition` | `\"left\"` \\| `\"right\"` | `\"left\"` | Mobile drawer side. |\n| `isMobileOpen` | `boolean` | — | Controlled mobile open. |\n| `setIsMobileOpen` | `(open: boolean) => void` | — | Set mobile open (when controlled). |\n| `showCollapsedTooltips` | `boolean` | `true` | Show tooltips when collapsed. |\n| `tooltipOptions` | `object` | — | Options for internal Tooltip. |\n\n## Item shape\n\n- `id`: string (required for expand/active).\n- `label`: string.\n- `icon`: ReactNode.\n- `children`: optional array of same shape (nested items).\n- `onClick`: optional handler.\n- `active`: optional boolean for current page.\n\n## Example\n\n```jsx\nconst [collapsed, setCollapsed] = useState(false);\n<Sidebar\n  items={[\n    { id: 'dash', label: 'Dashboard', icon: <Home /> },\n    { id: 'settings', label: 'Settings', icon: <Settings />, children: [\n      { id: 'profile', label: 'Profile' },\n      { id: 'security', label: 'Security' },\n    ]},\n  ]}\n  collapsed={collapsed}\n  onToggle={() => setCollapsed(!collapsed)}\n  logo={<Logo />}\n  user={{ name: 'Jane', avatar: '/jane.jpg' }}\n/>\n```\n\n[← Component overview](README.md)\n",
     "Skeleton": "# Skeleton\n\nPlaceholder blocks for loading states. Renders shimmer bars (or circles) when `active` is true; otherwise renders `children`.\n\n## Import\n\n```jsx\nimport { Skeleton } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `count` | `number` | `1` | Number of skeleton items. |\n| `circle` | `boolean` | `false` | Render items as circles. |\n| `height` | `number` \\| `string` | `16` | Height in px or CSS unit (e.g. `\"2rem\"`). |\n| `width` | `number` \\| `string` | — | Width; default 100% (column) or height (inline/circle). |\n| `rounded` | `boolean` | `true` | Rounded corners (when not circle). |\n| `animated` | `boolean` | `true` | Shimmer animation. |\n| `active` | `boolean` | `true` | If true show skeletons; if false render children. |\n| `gap` | `string` | `\"8px\"` | Spacing between items. |\n| `inline` | `boolean` | `false` | Layout items in a row. |\n| `className` | `string` | `\"\"` | Wrapper CSS classes. |\n| `style` | `object` | `{}` | Wrapper inline style. |\n| `children` | `ReactNode` | `null` | Rendered when `active` is false. |\n\n## Examples\n\n```jsx\n<Skeleton />\n<Skeleton count={3} height={20} gap=\"12px\" />\n<Skeleton circle height={40} />\n<Skeleton active={loading} count={2}>\n  <RealContent />\n</Skeleton>\n```\n\n[← Component overview](README.md)\n",
     "SpeechToText": "# SpeechToText\n\nVoice-to-text using the Web Speech API. Headless by default — render a custom\ncontrol via `renderButton`, or drive it imperatively through the ref. The\nbuilt-in fallback button is `className`-extensible and forwards arbitrary props.\n\n## Import\n\n```jsx\nimport { SpeechToText } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `lang` | `string` | `\"en-US\"` | Recognition language |\n| `continuous` | `boolean` | `true` | Keep listening until stopped (forced `false` on mobile) |\n| `interimResults` | `boolean` | `true` | Return interim results |\n| `onSpeechComplete` | `function` | — | Final transcript chunk callback `(text) => void` |\n| `onSpeaking` | `function` | — | Interim transcript callback `(text) => void` |\n| `onError` | `function` | — | Fatal error callback `(Error) => void`. Routine events (`no-speech`, `aborted`) are **not** surfaced |\n| `onStart` | `function` | — | Start callback |\n| `onStop` | `function` | — | Stop callback |\n| `renderButton` | `function` | — | Custom control render-prop (see signature below) |\n| `autoStart` | `boolean` | `false` | Start on mount (once, after support is detected) |\n| `disabled` | `boolean` | `false` | Disable |\n| `resetOnStart` | `boolean` | `false` | Clear the accumulated transcript when a new session starts |\n| `className` | `string` | — | Merged (via `cn`) onto the default button |\n| `...rest` | — | — | Forwarded to the default `<button>` |\n\nThe default button is keyboard-accessible (`aria-pressed`, `aria-label`) and\ntoken-driven. When `renderButton` is supplied, `className`/`...rest` are not\napplied (you own the rendered control).\n\n## `renderButton` signature\n\n```js\nrenderButton({ isListening, isSupported, error, start, stop, toggle, disabled })\n```\n\n## Ref methods\n\n`start()`, `stop()`, `toggle()`, `isListening()`, `isSupported()`,\n`getTranscript()`, `clearTranscript()`, `getError()`.\n\n## Example\n\n```jsx\nconst [transcript, setTranscript] = useState('');\n<SpeechToText\n  onSpeechComplete={(chunk) => setTranscript((t) => `${t} ${chunk}`.trim())}\n  onError={(e) => console.error(e)}\n/>\n<div>Transcript: {transcript}</div>\n```\n\n[← Component overview](README.md)\n",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamtree-org/twreact-ui",
-  "version": "1.1.64",
+  "version": "1.1.65",
   "description": "A comprehensive React + Tailwind components library for building modern web apps",
   "author": {
     "name": "Partha Preetham Krishna",