pixelize-design-library 2.4.2-beta.4 → 2.4.2-beta.41

package/dist/Components/RolesPermission/RolesPermission.js

@@ -8,7 +8,7 @@ const react_1 = require("react");
 const react_2 = require("@chakra-ui/react");
 const lucide_react_1 = require("lucide-react");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
-const outlineRung_1 = require("../../Theme/tokens/builders/outlineRung");
+const rowStates_1 = require("../../Theme/tokens/builders/rowStates");
 const Button_1 = __importDefault(require("../Button/Button"));
 const TextInput_1 = __importDefault(require("../Input/TextInput"));
 const EmptyState_1 = __importDefault(require("../EmptyState/EmptyState"));
@@ -56,6 +56,7 @@ const DEFAULT_KEYS = [
     "import",
     "export",
 ];
+/** Role list + role/permission-matrix form in one component (switch via `view`). */
 const RolesPermission = ({ view, mode = "create", roles, isRolesLoading = false, permissions, permissionKeys = DEFAULT_KEYS, roleName, roleNameError, isSuperAdmin, isTrackLocation, isShowRecords, isEditing = false, isSaving = false, onNewRole, onViewRole, onEditRole, onDeleteRole, onBack, onRoleNameChange, onToggleSuperAdmin, onToggleTrackLocation, onToggleShowRecords, onPermissionChange, onSave, onCancelForm, footerSlot, checkIcon, labels: labelOverrides, padding = "16px", }) => {
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
     const labels = (0, react_1.useMemo)(() => ({ ...DEFAULT_LABELS, ...labelOverrides }), [labelOverrides]);
@@ -64,8 +65,9 @@ const RolesPermission = ({ view, mode = "create", roles, isRolesLoading = false,
     const surface = colors.background[50];
     const muted = colors.textMuted;
     const heading = colors.text[900];
-    const headBg = colors.gray[50];
-    const rowHover = (0, outlineRung_1.resolveHoverTint)(colors.gray[50], surface);
+    const rowBackgrounds = (0, rowStates_1.listRowBackgrounds)(colors);
+    const headBg = colors.background[100];
+    const rowHover = rowBackgrounds.active;
     const isViewMode = mode === "view";
     const columnLabels = {
         read: labels.read,

package/dist/Components/RolesPermission/RolesPermissionProps.d.ts

@@ -1,6 +1,9 @@
 import { ReactNode } from "react";
+/** One column in the permission matrix — also the key passed to onPermissionChange. */
 export type PermissionKey = "read" | "create" | "edit" | "delete" | "import" | "export" | "automation";
+/** One row of the permission matrix, keyed by module — booleans mirror PermissionKey (automation is handled specially, see below). */
 export type Permission = {
+    /** "Automation" (case-insensitive) is special-cased: every column collapses to the single automation flag below, only the Read cell renders. */
     module: string;
     read: boolean;
     create: boolean;
@@ -10,19 +13,24 @@ export type Permission = {
     export?: boolean;
     automation?: boolean;
 };
+/** One row in the roles list — the same shape is passed back into onEditRole/onViewRole as the selected role. */
 export type RoleData = {
     roleName: string;
     createdBy: string;
     created_at: string;
     permission: Permission[];
+    /** Coerced via Number() before reaching onDeleteRole — a non-numeric id silently becomes NaN with no error. */
     roles_id: string;
+    /** designation/makeSuperAdmin/automation/trackLocation/show_records: never read by this component — pass-through only, for the consumer to prefill its own form state on edit/view. */
     designation: string;
     makeSuperAdmin?: boolean;
     automation?: boolean;
     trackLocation?: boolean;
     show_records?: boolean;
 };
+/** Top-level switch: "list" renders the roles table, "form" renders the create/edit/view role form. */
 export type RolesPermissionView = "list" | "form";
+/** Only relevant when view is "form" — mode "view" renders the permission form read-only. */
 export type RolesPermissionMode = "create" | "edit" | "view";
 /**
  * All user-facing strings. Provide translated values from the host app; every
@@ -63,6 +71,7 @@ export type RolesPermissionLabels = {
     deleteRole?: string;
     deleteRoleConfirm?: string;
 };
+/** Role list + role/permission-matrix form in one component (switch via `view`) — manages role definitions only, not user-to-role assignment (that's UserDetails' Change Role). */
 export interface RolesPermissionProps {
     /** Which view to render. */
     view: RolesPermissionView;
@@ -75,9 +84,10 @@ export interface RolesPermissionProps {
     permissions: Permission[];
     /** Columns rendered in the matrix. Defaults to all non-automation keys. */
     permissionKeys?: PermissionKey[];
-    /** Form field values (controlled). */
+    /** Form field values — fully controlled, no internal state; edits are invisible without the matching handler below. */
     roleName: string;
     roleNameError?: string;
+    /** Toggling this does not itself grant matrix permissions — it's cosmetic until the consumer applies that logic. */
     isSuperAdmin: boolean;
     isTrackLocation: boolean;
     isShowRecords: boolean;
@@ -89,15 +99,19 @@ export interface RolesPermissionProps {
     onNewRole?: () => void;
     onViewRole?: (role: RoleData) => void;
     onEditRole?: (role: RoleData) => void;
+    /** Called synchronously right before the modal closes — no await, no loading state; errors must be surfaced outside this flow. */
     onDeleteRole?: (roleId: number) => void;
+    /** Back icon renders only when this is provided, not merely disabled when omitted. */
     onBack?: () => void;
     /** Form actions. */
     onRoleNameChange?: (value: string) => void;
     onToggleSuperAdmin?: (checked: boolean) => void;
     onToggleTrackLocation?: (checked: boolean) => void;
     onToggleShowRecords?: (checked: boolean) => void;
+    /** Fires with key "automation" (not "read") for a module named "automation" — see Permission.module. */
     onPermissionChange?: (module: string, key: PermissionKey) => void;
     onSave?: () => void;
+    /** Header back icon renders only when set; the footer Cancel button always renders and no-ops without it. */
     onCancelForm?: () => void;
     /** App-specific sections rendered under the roles list (e.g. ModuleDelete, SignInActivity). */
     footerSlot?: ReactNode;
@@ -108,6 +122,7 @@ export interface RolesPermissionProps {
     /** Outer padding override. Defaults to a compact value. */
     padding?: string;
 }
+/** Plain confirm dialog for one role at a time — no built-in awaiting of onConfirm, so pair it with your own loading/error handling. */
 export interface DeleteRoleModalProps {
     isOpen: boolean;
     onClose: () => void;

package/dist/Components/ScrollToTop/ScrollToTop.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 export interface ScrollToTopProps {
-    /** Content to wrap. The button watches the nearest scrollable ancestor. */
+    /** Content to wrap. Watches this element's direct parentElement only — not a scroll-search up the tree. */
     children: React.ReactNode;
     /** Tooltip label on the button. */
     tooltipLabel?: string;
@@ -8,12 +8,13 @@ export interface ScrollToTopProps {
     threshold?: number;
     /** Smooth-scroll duration in ms. */
     duration?: number;
-    /** Pin to a window-level scroll instead of the wrapped parent. */
+    /** Pin to window-level scroll — also the fix when the real scroll container isn't the direct parent. */
     useWindow?: boolean;
     /** Distance from the bottom edge. */
     bottom?: string;
     /** Distance from the right edge. */
     right?: string;
 }
+/** Visibility depends on the wrapped content's direct parent actually scrolling — see `children`. */
 declare const ScrollToTop: React.FC<ScrollToTopProps>;
 export default ScrollToTop;

package/dist/Components/ScrollToTop/ScrollToTop.js

@@ -10,6 +10,8 @@ const lucide_react_1 = require("lucide-react");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
 const ToolTip_1 = __importDefault(require("../ToolTip/ToolTip"));
 const rafThrottle_1 = require("../../Utils/rafThrottle");
+const filledSurface_1 = require("../../Theme/tokens/builders/filledSurface");
+/** Visibility depends on the wrapped content's direct parent actually scrolling — see `children`. */
 const ScrollToTop = ({ children, tooltipLabel = "Scroll to top", threshold = 300, duration = 600, useWindow = false, bottom = "2rem", right = "2rem", }) => {
     const [visible, setVisible] = (0, react_1.useState)(false);
     const anchorRef = (0, react_1.useRef)(null);
@@ -62,8 +64,9 @@ const ScrollToTop = ({ children, tooltipLabel = "Scroll to top", threshold = 300
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [useWindow, threshold]);
-    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { ref: anchorRef, position: "relative", children: [children, (0, jsx_runtime_1.jsx)(ToolTip_1.default, { label: tooltipLabel, placement: "left", children: (0, jsx_runtime_1.jsx)(react_2.Box, { as: "button", type: "button", onClick: scrollToTop, "aria-label": tooltipLabel, border: "none", position: "fixed", bottom: bottom, right: right, zIndex: 1000, display: "flex", alignItems: "center", justifyContent: "center", boxSize: "44px", borderRadius: "full", cursor: "pointer", bg: theme.colors.primary[500], color: theme.colors.onPrimary, boxShadow: "md", opacity: visible ? 1 : 0, transform: visible ? "translateY(0) scale(1)" : "translateY(16px) scale(0.85)", pointerEvents: visible ? "auto" : "none", transition: "all 0.25s cubic-bezier(0.16, 1, 0.3, 1)", _hover: {
+    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { ref: anchorRef, position: "relative", children: [children, (0, jsx_runtime_1.jsx)(ToolTip_1.default, { label: tooltipLabel, placement: "left", children: (0, jsx_runtime_1.jsx)(react_2.Box, { as: "button", type: "button", onClick: scrollToTop, "aria-label": tooltipLabel, border: "none", position: "fixed", bottom: bottom, right: right, zIndex: 1000, display: "flex", alignItems: "center", justifyContent: "center", boxSize: "44px", borderRadius: "full", cursor: "pointer", bg: theme.colors.primary[(0, filledSurface_1.solidFillRung)(theme.colors.primary, theme.colors.white)], color: (0, filledSurface_1.labelOnFill)(theme.colors.primary[(0, filledSurface_1.solidFillRung)(theme.colors.primary, theme.colors.white)], theme.colors.white, theme.colors.black), boxShadow: "md", opacity: visible ? 1 : 0, transform: visible ? "translateY(0) scale(1)" : "translateY(16px) scale(0.85)", pointerEvents: visible ? "auto" : "none", transition: "all 0.25s cubic-bezier(0.16, 1, 0.3, 1)", _hover: {
                         bg: theme.colors.primary[600],
+                        color: (0, filledSurface_1.labelOnFill)(theme.colors.primary[600], theme.colors.white, theme.colors.black),
                         transform: "translateY(-2px) scale(1.05)",
                         boxShadow: "lg",
                     }, _active: { transform: "scale(0.95)" }, children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronUp, { size: 24, strokeWidth: 2.5 }) }) })] }));

package/dist/Components/ScrollbarBox/ScrollbarBox.d.ts

@@ -2,12 +2,19 @@ import React, { ReactNode } from "react";
 import { ScrollbarVariant } from "../../Theme/tokens/builders/scrollbar";
 export interface ScrollbarBoxProps {
     children: ReactNode;
+    /** Fixed box height; omit to let content size the box instead of scrolling it. */
     height?: string;
+    /** Caps growth and enables scrolling; without it the box grows unbounded. */
     maxHeight?: string;
+    /** No default (unlike overflowY) — falls through to the browser's normal overflow. */
     overflowX?: string;
+    /** Defaults to "auto" — scrolls only once content exceeds height/maxHeight. */
     overflowY?: string;
+    /** Picks the scrollbar chrome from scrollbarStyles; see scrollbar.ts for what each looks like. */
     variant?: ScrollbarVariant;
+    /** Forwarded to the underlying Box so a consumer can read/scroll the container from outside. */
     scrollContainerRef?: React.Ref<HTMLDivElement> | null;
 }
+/** Scrollable Box with themed scrollbar chrome (scrollbarStyles) applied via variant. */
 declare const ScrollbarBox: React.FC<ScrollbarBoxProps>;
 export default ScrollbarBox;

package/dist/Components/ScrollbarBox/ScrollbarBox.js

@@ -4,6 +4,7 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("@chakra-ui/react");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
 const scrollbar_1 = require("../../Theme/tokens/builders/scrollbar");
+/** Scrollable Box with themed scrollbar chrome (scrollbarStyles) applied via variant. */
 const ScrollbarBox = ({ children, height, maxHeight, overflowX, overflowY = "auto", variant = "default", scrollContainerRef, }) => {
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
     return ((0, jsx_runtime_1.jsx)(react_1.Box, { ref: scrollContainerRef, height: height, maxHeight: maxHeight, position: "relative", sx: { overflowX, overflowY, ...(0, scrollbar_1.scrollbarStyles)(colors, variant) }, children: children }));

package/dist/Components/Search/Search.d.ts

@@ -1,2 +1,3 @@
 import { SearchProps } from "./SearchProps";
+/** Plain filter/search input, no options list — default shortcut registers a page-global Ctrl+K listener that can't be disabled. */
 export default function Search({ placeholder, onSearch, onclose, shortcut, query, error, errorMessage, helperText, label, id, isInformation, informationMessage, isRequired, }: SearchProps): import("react/jsx-runtime").JSX.Element;

package/dist/Components/Search/Search.js

@@ -12,6 +12,7 @@ const FormLabel_1 = require("../Common/FormLabel");
 const HelperText_1 = __importDefault(require("../Common/HelperText"));
 const ErrorMessage_1 = __importDefault(require("../Common/ErrorMessage"));
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
+/** Plain filter/search input, no options list — default shortcut registers a page-global Ctrl+K listener that can't be disabled. */
 function Search({ placeholder = "Search...", onSearch, onclose, shortcut = "Ctrl+K", query, error, errorMessage, helperText, label, id, isInformation, informationMessage, isRequired, }) {
     const theme = (0, useCustomTheme_1.useCustomTheme)();
     const inputRef = (0, react_1.useRef)(null);
@@ -30,6 +31,6 @@ function Search({ placeholder = "Search...", onSearch, onclose, shortcut = "Ctrl
             window.removeEventListener("keydown", handleKeyDown);
         };
     }, [shortcut]);
-    return ((0, jsx_runtime_1.jsxs)(react_2.FormControl, { id: id, isInvalid: !!error, children: [label && ((0, jsx_runtime_1.jsx)(FormLabel_1.TextLabel, { label: label, id: id, isInformation: isInformation, informationMessage: informationMessage, isRequired: isRequired })), (0, jsx_runtime_1.jsxs)(react_2.InputGroup, { w: "100%", children: [(0, jsx_runtime_1.jsx)(react_2.InputLeftElement, { pointerEvents: "none", children: (0, jsx_runtime_1.jsx)(react_2.Icon, { as: lucide_react_1.Search, color: theme.colors.gray[500] }) }), (0, jsx_runtime_1.jsx)(react_2.Input, { ref: inputRef, type: "text", value: query, onChange: onSearch, placeholder: placeholder, variant: "outline", isInvalid: error }), (0, jsx_runtime_1.jsxs)(react_2.InputRightElement, { w: "auto", pr: "3", display: "flex", alignItems: "center" // ✅ centers vertically
-                        , gap: "2", children: [query && ((0, jsx_runtime_1.jsx)(react_2.Icon, { as: lucide_react_1.X, color: theme.colors.gray[500], boxSize: 5, cursor: "pointer", onClick: onclose })), shortcut && ((0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: "sm", color: theme.colors.gray[500], px: "2", py: "0.5", borderRadius: "md", bg: theme.colors.gray[100], children: shortcut }))] })] }), error && (0, jsx_runtime_1.jsx)(ErrorMessage_1.default, { errorMessage: errorMessage }), helperText && !error && (0, jsx_runtime_1.jsx)(HelperText_1.default, { helperText: helperText })] }));
+    return ((0, jsx_runtime_1.jsxs)(react_2.FormControl, { id: id, isInvalid: !!error, children: [label && ((0, jsx_runtime_1.jsx)(FormLabel_1.TextLabel, { label: label, id: id, isInformation: isInformation, informationMessage: informationMessage, isRequired: isRequired })), (0, jsx_runtime_1.jsxs)(react_2.InputGroup, { w: "100%", children: [(0, jsx_runtime_1.jsx)(react_2.InputLeftElement, { pointerEvents: "none", children: (0, jsx_runtime_1.jsx)(react_2.Icon, { as: lucide_react_1.Search, color: theme.colors.textMuted }) }), (0, jsx_runtime_1.jsx)(react_2.Input, { ref: inputRef, type: "text", value: query, onChange: onSearch, placeholder: placeholder, variant: "outline", isInvalid: error }), (0, jsx_runtime_1.jsxs)(react_2.InputRightElement, { w: "auto", pr: "3", display: "flex", alignItems: "center" // ✅ centers vertically
+                        , gap: "2", children: [query && ((0, jsx_runtime_1.jsx)(react_2.Icon, { as: lucide_react_1.X, color: theme.colors.textMuted, boxSize: 5, cursor: "pointer", onClick: onclose })), shortcut && ((0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: "sm", color: theme.colors.textMuted, px: "2", py: "0.5", borderRadius: "md", bg: theme.colors.backgroundColor.subtle, children: shortcut }))] })] }), error && (0, jsx_runtime_1.jsx)(ErrorMessage_1.default, { errorMessage: errorMessage }), helperText && !error && (0, jsx_runtime_1.jsx)(HelperText_1.default, { helperText: helperText })] }));
 }

package/dist/Components/Search/SearchProps.d.ts

@@ -1,6 +1,8 @@
+/** Fully controlled — query and clearing it are owned by the caller; onclose only fires the callback, it doesn't clear query itself. */
 export type SearchProps = {
     placeholder?: string;
     onSearch: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Only "Ctrl+K" is valid, and the type has no "off" value — every mounted Search grabs this hotkey globally. */
     shortcut?: "Ctrl+K";
     query?: string;
     onclose: () => void;

package/dist/Components/SearchSelect/SearchSelect.d.ts

@@ -1,3 +1,4 @@
 import { SearchSelectProps } from "./SearchSelectProps";
+/** Full-featured combobox: search, chips, select-all, paginated infinite scroll — not DOM-virtualized despite the `virtualization` prop. */
 declare const SearchSelect: ({ id, label, options, onSelect, onSearch, isOptionLoading, isLoading, loadingText, placeholder, value, searchQuery, isMultiple, isRequired, error, errorMessage, helperText, width, height, size, chip, information, isInformation, informationMessage, rightIcon, addNew, isSelectAll, pagination, insideSelect, isRemoveAllIcon, }: SearchSelectProps) => import("react/jsx-runtime").JSX.Element;
 export default SearchSelect;

package/dist/Components/SearchSelect/SearchSelect.js

@@ -43,6 +43,9 @@ const lucide_react_1 = require("lucide-react");
 const FormLabel_1 = require("../Common/FormLabel");
 const Tag_1 = __importDefault(require("../Tag/Tag"));
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
+const placeholderInk_1 = require("../../Theme/tokens/builders/placeholderInk");
+const rowStates_1 = require("../../Theme/tokens/builders/rowStates");
+const useExclusiveOverlay_1 = require("../../Hooks/useExclusiveOverlay");
 const ErrorMessage_1 = __importDefault(require("../Common/ErrorMessage"));
 const HelperText_1 = __importDefault(require("../Common/HelperText"));
 const ToolTip_1 = __importDefault(require("../ToolTip/ToolTip"));
@@ -62,6 +65,7 @@ const normalizeMultiValue = (val) => {
     }
     return [];
 };
+/** Full-featured combobox: search, chips, select-all, paginated infinite scroll — not DOM-virtualized despite the `virtualization` prop. */
 const SearchSelect = ({ id, label, options, onSelect, onSearch, isOptionLoading = false, isLoading = false, loadingText = "Loading...", placeholder = "Select", value, searchQuery = "", isMultiple = false, isRequired = false, error = false, errorMessage, helperText, width = "100%", height, size = "md", chip, information, isInformation, informationMessage, rightIcon, addNew, isSelectAll = false, pagination, insideSelect, isRemoveAllIcon, }) => {
     var _a, _b;
     const s = (0, searchSelectSize_1.getSearchSelectSizeStyles)((size || "md"));
@@ -87,12 +91,11 @@ const SearchSelect = ({ id, label, options, onSelect, onSearch, isOptionLoading
         width: 0,
     });
     const theme = (0, useCustomTheme_1.useCustomTheme)();
-    // `searchselect-dropdown-portal` is also the DOM id an existing outside-click check and
-    // several tests look up directly — kept as a literal constant, not derived from `baseId`,
-    // so those keep working unchanged.
+    const rowBackgrounds = (0, react_1.useMemo)(() => (0, rowStates_1.listRowBackgrounds)(theme.colors), [theme.colors]);
     const generatedId = (0, react_1.useId)();
     const baseId = id || generatedId;
-    const listboxId = "searchselect-dropdown-portal";
+    const listboxId = `${baseId}-listbox`;
+    const insideSelectPortalId = `${baseId}-inside-select`;
     const getOptionId = (index) => `${baseId}-option-${index}`;
     const [activeIndex, setActiveIndex] = (0, react_1.useState)(-1);
     const pendingFocusRestoreRef = (0, react_1.useRef)(false);
@@ -102,12 +105,15 @@ const SearchSelect = ({ id, label, options, onSelect, onSearch, isOptionLoading
     // just "Input is mounted now": falling back to render-condition guessing there would put
     // aria-activedescendant on an unfocused Input while the still-focused toggle button gets none.
     const [focusedTrigger, setFocusedTrigger] = (0, react_1.useState)(null);
+    const closeMenus = (0, react_1.useCallback)(() => {
+        setIsOpen(false);
+        setCustomSelectOpen(false);
+    }, []);
+    const requestExclusiveOpen = (0, useExclusiveOverlay_1.useExclusiveOverlay)(isOpen || customSelectOpen, closeMenus);
     (0, react_2.useOutsideClick)({
         ref: containerRef,
         handler: (e) => {
-            // The options dropdown is portaled to <body>, so a click on it is "outside"
-            // the container — ignore those so selecting an option doesn't close first.
-            const dropdown = document.getElementById(listboxId);
+            const dropdown = dropdownMenuRef.current;
             if (dropdown && dropdown.contains(e.target))
                 return;
             setIsOpen(false);
@@ -214,6 +220,7 @@ const SearchSelect = ({ id, label, options, onSelect, onSearch, isOptionLoading
     // Opens only — matches SelectV2's convention of a first ArrowDown/Enter/Space that opens with
     // nothing highlighted yet, and a second keypress that moves onto the first/last option.
     const openMenu = () => {
+        requestExclusiveOpen();
         setCustomSelectOpen(false);
         setIsOpen(true);
     };
@@ -358,7 +365,7 @@ const SearchSelect = ({ id, label, options, onSelect, onSearch, isOptionLoading
     (0, react_2.useOutsideClick)({
         ref: customSelectRef,
         handler: (e) => {
-            const dropdown = document.getElementById("custom-select-portal");
+            const dropdown = insideSelectMenuRef.current;
             if (dropdown && dropdown.contains(e.target))
                 return;
             setCustomSelectOpen(false);
@@ -474,38 +481,39 @@ const SearchSelect = ({ id, label, options, onSelect, onSearch, isOptionLoading
                         ? theme.colors.semanticText.error
                         : focused
                             ? theme.colors.primary[500]
-                            : theme.colors.boxborder[500], borderRadius: "lg", bg: theme.colors.gray[50], boxShadow: focused
+                            : theme.colors.boxborder[500], borderRadius: "lg", bg: theme.colors.background[50], boxShadow: focused
                         ? error
                             ? `0 0 0 0.125rem ${theme.colors.boxShadow.error}`
                             : `0 0 0 0.125rem ${theme.colors.boxShadow.primary}`
                         : error
                             ? `0 0 0 0.125rem ${theme.colors.boxShadow.error}`
-                            : "none", transition: "box-shadow 0.2s, border-color 0.2s", onKeyDown: handleControlKeyDown, onFocus: () => setFocused(true), onBlur: () => setFocused(false), onClick: () => {
-                        setCustomSelectOpen(false);
-                        setIsOpen(true);
-                    }, children: [insideSelect && (() => {
+                            : "none", transition: "box-shadow 0.2s, border-color 0.2s", onKeyDown: handleControlKeyDown, onFocus: () => setFocused(true), onBlur: () => setFocused(false), onClick: () => openMenu(), children: [insideSelect && (() => {
                             var _a, _b, _c, _d, _e;
                             const insideLabel = (_a = insideSelect.value) === null || _a === void 0 ? void 0 : _a.label;
                             const insidePlaceholder = (_b = insideSelect.placeholder) !== null && _b !== void 0 ? _b : "Select";
                             return ((0, jsx_runtime_1.jsxs)(react_2.Box, { position: "relative", ref: customSelectRef, flexShrink: 0, ml: s.insideSelectMarginLeft, h: "-webkit-fill-available", borderRight: "0.063rem solid", borderColor: theme.colors.boxborder[200], bg: customSelectOpen
-                                    ? theme.colors.primary.opacity[8]
+                                    ? rowBackgrounds.active
                                     : theme.colors.background[400], borderLeftRadius: "md", borderRightRadius: 0, transition: "background 0.15s ease, box-shadow 0.15s ease", boxShadow: customSelectOpen
                                     ? `inset 0 0 0 0.063rem ${theme.colors.primary[500]}`
                                     : "none", onClick: (e) => {
                                     e.stopPropagation();
                                     setIsOpen(false);
-                                    setCustomSelectOpen((prev) => !prev);
-                                }, children: [(0, jsx_runtime_1.jsxs)(react_2.Box, { minW: "4.5rem", cursor: "pointer", display: "flex", justifyContent: "space-between", alignItems: "center", gap: 1, width: insideSelect.width, height: insideSelectBoxHeight, pl: "0.5rem", pr: "0.375rem", children: [insideLabel ? ((0, jsx_runtime_1.jsx)(SelectTruncatedLabel_1.default, { label: insideLabel, maxWidth: insideSelect.width || "6rem", fontSize: s.fieldFontSize })) : ((0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.fieldFontSize, fontWeight: 500, color: theme.colors.placeholder[500], isTruncated: true, maxW: insideSelect.width || "6rem", children: insidePlaceholder })), (0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", flexShrink: 0, color: customSelectOpen ? theme.colors.accentText : theme.colors.textMuted, transition: "transform 0.2s ease, color 0.15s ease", transform: customSelectOpen ? "rotate(180deg)" : "rotate(0deg)", children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: s.chevronSize }) })] }), customSelectOpen && ((0, jsx_runtime_1.jsx)(react_2.Portal, { children: (0, jsx_runtime_1.jsx)(react_2.Box, { ref: setInsideSelectMenuRef, id: "custom-select-portal", position: "fixed", top: `${customSelectPos.top}px`, left: `${customSelectPos.left}px`, zIndex: 1510, bg: theme.colors.background[50], border: "0.063rem solid", borderColor: theme.colors.boxborder[200], borderRadius: "lg", boxShadow: (_d = (_c = theme.shadows) === null || _c === void 0 ? void 0 : _c.md) !== null && _d !== void 0 ? _d : "md", minW: `${customSelectPos.width}px`, maxW: "20rem", py: 1, overflow: "hidden", children: (_e = insideSelect.option) === null || _e === void 0 ? void 0 : _e.map((item) => {
+                                    if (customSelectOpen) {
+                                        setCustomSelectOpen(false);
+                                    }
+                                    else {
+                                        requestExclusiveOpen();
+                                        setCustomSelectOpen(true);
+                                    }
+                                }, children: [(0, jsx_runtime_1.jsxs)(react_2.Box, { minW: "4.5rem", cursor: "pointer", display: "flex", justifyContent: "space-between", alignItems: "center", gap: 1, width: insideSelect.width, height: insideSelectBoxHeight, pl: "0.5rem", pr: "0.375rem", children: [insideLabel ? ((0, jsx_runtime_1.jsx)(SelectTruncatedLabel_1.default, { label: insideLabel, maxWidth: insideSelect.width || "6rem", fontSize: s.fieldFontSize })) : ((0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.fieldFontSize, fontWeight: 500, color: (0, placeholderInk_1.placeholderInk)(theme.colors), isTruncated: true, maxW: insideSelect.width || "6rem", children: insidePlaceholder })), (0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", flexShrink: 0, color: customSelectOpen ? theme.colors.accentText : theme.colors.textMuted, transition: "transform 0.2s ease, color 0.15s ease", transform: customSelectOpen ? "rotate(180deg)" : "rotate(0deg)", children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: s.chevronSize }) })] }), customSelectOpen && ((0, jsx_runtime_1.jsx)(react_2.Portal, { children: (0, jsx_runtime_1.jsx)(react_2.Box, { ref: setInsideSelectMenuRef, id: insideSelectPortalId, position: "fixed", top: `${customSelectPos.top}px`, left: `${customSelectPos.left}px`, zIndex: 1510, bg: theme.colors.background[50], border: "0.063rem solid", borderColor: theme.colors.boxborder[200], borderRadius: "lg", boxShadow: (_d = (_c = theme.shadows) === null || _c === void 0 ? void 0 : _c.md) !== null && _d !== void 0 ? _d : "md", minW: `${customSelectPos.width}px`, maxW: "20rem", py: 1, overflow: "hidden", children: (_e = insideSelect.option) === null || _e === void 0 ? void 0 : _e.map((item) => {
                                                 var _a;
                                                 const selected = ((_a = insideSelect.value) === null || _a === void 0 ? void 0 : _a.id) === item.id;
                                                 return ((0, jsx_runtime_1.jsxs)(react_2.Box, { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 2, minH: s.optionRowMinH, py: s.optionRowPy, px: "0.75rem", fontSize: s.dropdownTextFontSize, fontWeight: selected ? 600 : 500, color: selected
                                                         ? theme.colors.accentText
-                                                        : theme.colors.text[700], bg: selected
-                                                        ? theme.colors.primary.opacity[8]
-                                                        : "transparent", _hover: {
+                                                        : theme.colors.text[700], bg: selected ? rowBackgrounds.selected : "transparent", _hover: {
                                                         bg: selected
-                                                            ? theme.colors.primary.opacity[8]
-                                                            : theme.colors.gray[50],
+                                                            ? rowBackgrounds.selectedActive
+                                                            : rowBackgrounds.active,
                                                     }, cursor: "pointer", onClick: (e) => {
                                                         e.stopPropagation();
                                                         handleCustomSelect(item);
@@ -518,16 +526,12 @@ const SearchSelect = ({ id, label, options, onSelect, onSearch, isOptionLoading
                                     ? item.label.slice(0, chip.maxText) + "…"
                                     : item.label, onIconClick: (chip === null || chip === void 0 ? void 0 : chip.onClick) ? () => handleRemove(item === null || item === void 0 ? void 0 : item.id) : undefined, icon: (chip === null || chip === void 0 ? void 0 : chip.onClick) ? lucide_react_1.CircleX : undefined, colorScheme: "gray", size: s.tagSize }, item.id)))
                             : selectedValues.length === 1 &&
-                                !isOpen && ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "button", type: "button", ref: triggerButtonRef, id: primaryTarget === "button" ? baseId : undefined, ...comboboxA11yProps("button"), "aria-label": !label ? String((_b = (_a = selectedValues[0]) === null || _a === void 0 ? void 0 : _a.label) !== null && _b !== void 0 ? _b : "") : undefined, onFocus: () => setFocusedTrigger("button"), onBlur: () => setFocusedTrigger((prev) => (prev === "button" ? null : prev)), onClick: () => {
-                                    setCustomSelectOpen(false);
-                                    setIsOpen(true);
-                                }, fontSize: s.fieldFontSize, color: theme.colors.gray[800], background: "transparent", border: "none", cursor: "pointer", p: 0, display: "flex", alignItems: "center", flex: "1", minW: 0, children: (0, jsx_runtime_1.jsx)(SelectTruncatedLabel_1.default, { label: String(selectedValues[0].label), maxWidth: "calc(100% - 2rem)", fontSize: s.fieldFontSize }) })), (chip === null || chip === void 0 ? void 0 : chip.maxChips) && isMultiple && selectedValues.length > chip.maxChips && ((0, jsx_runtime_1.jsx)(Tag_1.default, { label: `+ ${selectedValues.length - chip.maxChips}`, colorScheme: "gray", size: s.tagSize }, "extra-count")), (isOpen || inputValue || !selectedValues.length) && ((0, jsx_runtime_1.jsx)(react_2.Input, { ref: inputRef, id: primaryTarget === "input" ? baseId : undefined, "aria-autocomplete": "list", ...comboboxA11yProps("input"), variant: "unstyled", size: size, h: s.fieldHeight, minH: s.fieldHeight, fontSize: s.fieldFontSize, flex: "1", 
+                                !isOpen && ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "button", type: "button", ref: triggerButtonRef, id: primaryTarget === "button" ? baseId : undefined, ...comboboxA11yProps("button"), "aria-label": !label ? String((_b = (_a = selectedValues[0]) === null || _a === void 0 ? void 0 : _a.label) !== null && _b !== void 0 ? _b : "") : undefined, onFocus: () => setFocusedTrigger("button"), onBlur: () => setFocusedTrigger((prev) => (prev === "button" ? null : prev)), onClick: () => openMenu(), fontSize: s.fieldFontSize, color: theme.colors.gray[800], background: "transparent", border: "none", cursor: "pointer", p: 0, display: "flex", alignItems: "center", flex: "1", minW: 0, children: (0, jsx_runtime_1.jsx)(SelectTruncatedLabel_1.default, { label: String(selectedValues[0].label), maxWidth: "calc(100% - 2rem)", fontSize: s.fieldFontSize }) })), (chip === null || chip === void 0 ? void 0 : chip.maxChips) && isMultiple && selectedValues.length > chip.maxChips && ((0, jsx_runtime_1.jsx)(Tag_1.default, { label: `+ ${selectedValues.length - chip.maxChips}`, colorScheme: "gray", size: s.tagSize }, "extra-count")), (isOpen || inputValue || !selectedValues.length) && ((0, jsx_runtime_1.jsx)(react_2.Input, { ref: inputRef, id: primaryTarget === "input" ? baseId : undefined, "aria-autocomplete": "list", ...comboboxA11yProps("input"), variant: "unstyled", size: size, h: s.fieldHeight, minH: s.fieldHeight, fontSize: s.fieldFontSize, flex: "1", 
                             // minW="5rem"
                             minW: "0", value: inputValue, onChange: (e) => setInputValue(e.target.value), onFocus: () => {
                                 setFocused(true);
                                 setFocusedTrigger("input");
-                                setCustomSelectOpen(false);
-                                setIsOpen(true);
+                                openMenu();
                             }, onBlur: () => {
                                 setFocused(false);
                                 setFocusedTrigger((prev) => (prev === "input" ? null : prev));
@@ -539,15 +543,22 @@ const SearchSelect = ({ id, label, options, onSelect, onSearch, isOptionLoading
                                         } }) })), isLoading ? ((0, jsx_runtime_1.jsx)(react_2.Spinner, { size: s.spinnerSize })) : isValidIcon(rightIcon === null || rightIcon === void 0 ? void 0 : rightIcon.icon) ? ((0, jsx_runtime_1.jsx)(react_2.IconButton, { icon: rightIcon === null || rightIcon === void 0 ? void 0 : rightIcon.icon, "aria-label": "right-icon", variant: "ghost", size: s.iconButtonSize, onClick: rightIcon === null || rightIcon === void 0 ? void 0 : rightIcon.onClick })) : ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "button", type: "button", ref: toggleButtonRef, id: primaryTarget === "toggle" ? baseId : undefined, ...comboboxA11yProps("toggle"), onFocus: () => setFocusedTrigger("toggle"), onBlur: () => setFocusedTrigger((prev) => (prev === "toggle" ? null : prev)), onClick: (e) => {
                                         e.preventDefault();
                                         e.stopPropagation();
-                                        setIsOpen((prev) => {
-                                            if (!prev)
-                                                setCustomSelectOpen(false);
-                                            return !prev;
-                                        });
-                                    }, "aria-label": "toggle-dropdown", display: "flex", alignItems: "center", children: isOpen ? ((0, jsx_runtime_1.jsx)(lucide_react_1.ChevronUp, { size: s.chevronSize })) : ((0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: s.chevronSize })) }))] })] }) }), isOpen && ((0, jsx_runtime_1.jsx)(react_2.Portal, { children: (0, jsx_runtime_1.jsxs)(react_2.Box, { ref: setDropdownMenuRef, id: listboxId, role: "listbox", "aria-multiselectable": isMultiple || undefined, position: "fixed", top: `${dropdownPos.top}px`, left: `${dropdownPos.left}px`, width: `${dropdownPos.width}px`, zIndex: 1500, maxH: "20rem", borderWidth: 1, borderColor: theme.colors.boxborder[200], borderRadius: "sm", bg: theme.colors.background[50], boxShadow: "md", display: "flex", flexDirection: "column", children: [isMultiple && isSelectAll && ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: s.optionRowPy, px: 3, cursor: "pointer", onClick: handleSelectAll, display: "flex", alignItems: "center", gap: 2, borderBottom: `0.063rem solid ${theme.colors.boxborder[200]}`, children: [(0, jsx_runtime_1.jsx)(Checkbox_1.default, { isChecked: allFilteredSelected, sx: { pointerEvents: "none" }, size: s.checkboxSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: allFilteredSelected ? "Unselect All" : "Select All" })] })), (0, jsx_runtime_1.jsx)(react_2.Box, { flex: "1", overflowY: "auto", onScroll: handleScroll, maxH: "15rem", borderBottom: "0.063rem solid", borderColor: theme.colors.boxborder[200], children: isOptionLoading && filteredOptions.length === 0 ? ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: s.optionRowPy, px: 3, display: "flex", alignItems: "center", gap: 2, minH: s.optionRowMinH, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: s.spinnerSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: loadingText })] })) : !isOptionLoading && filteredOptions.length === 0 ? ((0, jsx_runtime_1.jsx)(react_2.Text, { p: 3, fontSize: s.dropdownTextFontSize, color: theme.colors.textMuted, children: "No results found" })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [filteredOptions.map((option, index) => ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: getOptionId(index), role: "option", "aria-selected": isSelected(option.id), py: s.optionRowPy, px: 3, minH: s.optionRowMinH, cursor: "pointer", bg: index === activeIndex
-                                            ? theme.colors.primary.opacity[8]
-                                            : isSelected(option.id)
-                                                ? theme.colors.gray[100]
-                                                : "transparent", _hover: { bg: theme.colors.gray[50] }, onClick: () => handleSelect(option), onMouseEnter: () => setActiveIndex(index), display: "flex", alignItems: "center", gap: 2, borderBottom: `0.063rem solid ${theme.colors.boxborder[200]}`, children: [isMultiple && ((0, jsx_runtime_1.jsx)(Checkbox_1.default, { isChecked: isSelected(option.id), sx: { pointerEvents: "none" }, size: s.checkboxSize })), option.view ? ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: option.view })) : ((0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: option.label }))] }, option.id))), ((pagination === null || pagination === void 0 ? void 0 : pagination.scrollLoading) || (isOptionLoading && filteredOptions.length > 0)) && ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: s.optionRowPy, px: 3, display: "flex", alignItems: "center", justifyContent: "center", gap: 2, minH: s.optionRowMinH, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: s.spinnerSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: loadingText })] }))] })) }), (addNew === null || addNew === void 0 ? void 0 : addNew.enabled) && ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: s.optionRowPy, px: 3, borderTop: "0.063rem solid", borderColor: theme.colors.boxborder[200], bg: theme.colors.background[50], display: "flex", alignItems: "center", gap: 2, minH: s.optionRowMinH, cursor: "pointer", onClick: addNew.onClick, _hover: { bg: theme.colors.gray[50] }, children: [addNew.icon || (0, jsx_runtime_1.jsx)(lucide_react_1.Plus, { size: s.addNewIconSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: addNew.text || "Add New" })] }))] }) })), helperText && !error && (0, jsx_runtime_1.jsx)(HelperText_1.default, { helperText: helperText }), error && (0, jsx_runtime_1.jsx)(ErrorMessage_1.default, { errorMessage: errorMessage })] }));
+                                        if (isOpen) {
+                                            closeMenus();
+                                        }
+                                        else {
+                                            openMenu();
+                                        }
+                                    }, "aria-label": "toggle-dropdown", display: "flex", alignItems: "center", children: isOpen ? ((0, jsx_runtime_1.jsx)(lucide_react_1.ChevronUp, { size: s.chevronSize })) : ((0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: s.chevronSize })) }))] })] }) }), isOpen && ((0, jsx_runtime_1.jsx)(react_2.Portal, { children: (0, jsx_runtime_1.jsxs)(react_2.Box, { ref: setDropdownMenuRef, id: listboxId, role: "listbox", "aria-multiselectable": isMultiple || undefined, position: "fixed", top: `${dropdownPos.top}px`, left: `${dropdownPos.left}px`, width: `${dropdownPos.width}px`, zIndex: 1500, maxH: "20rem", borderWidth: 1, borderColor: theme.colors.boxborder[200], borderRadius: "sm", bg: theme.colors.background[50], boxShadow: "md", display: "flex", flexDirection: "column", children: [isMultiple && isSelectAll && ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: s.optionRowPy, px: 3, cursor: "pointer", onClick: handleSelectAll, display: "flex", alignItems: "center", gap: 2, borderBottom: `0.063rem solid ${theme.colors.boxborder[200]}`, children: [(0, jsx_runtime_1.jsx)(Checkbox_1.default, { isChecked: allFilteredSelected, sx: { pointerEvents: "none" }, size: s.checkboxSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: allFilteredSelected ? "Unselect All" : "Select All" })] })), (0, jsx_runtime_1.jsx)(react_2.Box, { flex: "1", overflowY: "auto", onScroll: handleScroll, maxH: "15rem", borderBottom: "0.063rem solid", borderColor: theme.colors.boxborder[200], children: isOptionLoading && filteredOptions.length === 0 ? ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: s.optionRowPy, px: 3, display: "flex", alignItems: "center", gap: 2, minH: s.optionRowMinH, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: s.spinnerSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: loadingText })] })) : !isOptionLoading && filteredOptions.length === 0 ? ((0, jsx_runtime_1.jsx)(react_2.Text, { p: 3, fontSize: s.dropdownTextFontSize, color: theme.colors.textMuted, children: "No results found" })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [filteredOptions.map((option, index) => ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: getOptionId(index), role: "option", "aria-selected": isSelected(option.id), py: s.optionRowPy, px: 3, minH: s.optionRowMinH, cursor: "pointer", bg: isSelected(option.id)
+                                            ? index === activeIndex
+                                                ? rowBackgrounds.selectedActive
+                                                : rowBackgrounds.selected
+                                            : index === activeIndex
+                                                ? rowBackgrounds.active
+                                                : "transparent", _hover: {
+                                            bg: isSelected(option.id)
+                                                ? rowBackgrounds.selectedActive
+                                                : rowBackgrounds.active,
+                                        }, onClick: () => handleSelect(option), onMouseEnter: () => setActiveIndex(index), display: "flex", alignItems: "center", gap: 2, borderBottom: `0.063rem solid ${theme.colors.boxborder[200]}`, children: [isMultiple && ((0, jsx_runtime_1.jsx)(Checkbox_1.default, { isChecked: isSelected(option.id), sx: { pointerEvents: "none" }, size: s.checkboxSize })), option.view ? ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: option.view })) : ((0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: option.label }))] }, option.id))), ((pagination === null || pagination === void 0 ? void 0 : pagination.scrollLoading) || (isOptionLoading && filteredOptions.length > 0)) && ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: s.optionRowPy, px: 3, display: "flex", alignItems: "center", justifyContent: "center", gap: 2, minH: s.optionRowMinH, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: s.spinnerSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: loadingText })] }))] })) }), (addNew === null || addNew === void 0 ? void 0 : addNew.enabled) && ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: s.optionRowPy, px: 3, borderTop: "0.063rem solid", borderColor: theme.colors.boxborder[200], bg: theme.colors.background[50], display: "flex", alignItems: "center", gap: 2, minH: s.optionRowMinH, cursor: "pointer", onClick: addNew.onClick, _hover: { bg: rowBackgrounds.active }, children: [addNew.icon || (0, jsx_runtime_1.jsx)(lucide_react_1.Plus, { size: s.addNewIconSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: s.dropdownTextFontSize, children: addNew.text || "Add New" })] }))] }) })), helperText && !error && (0, jsx_runtime_1.jsx)(HelperText_1.default, { helperText: helperText }), error && (0, jsx_runtime_1.jsx)(ErrorMessage_1.default, { errorMessage: errorMessage })] }));
 };
 exports.default = SearchSelect;

package/dist/Components/SearchSelect/SearchSelectProps.d.ts

@@ -1,61 +1,84 @@
+/** value's shape must match isMultiple (array vs single object) — a mismatch normalizes to no selection, not an error. */
 export type SearchSelectProps = {
     id?: string;
     label?: string;
+    /** Filtered against option.label only — a custom `view` node's visible text isn't searchable. */
     options: Options[];
+    /** Required for selections to stick — the component is fully controlled, no internal selected state. */
     onSelect?: (options: Options | Options[] | undefined) => void;
+    /** Fires 1s after typing stops; local filtering against `options` already runs synchronously regardless. */
     onSearch?: (value: string) => void;
     isOptionLoading?: boolean;
+    /** Overrides rightIcon — replaces it with a spinner in the trailing slot whenever true. */
     isLoading?: boolean;
     loadingText?: string;
     placeholder?: string;
     value?: Options[] | Options;
+    /** Only seeds the initial input text at mount — later prop changes don't resync the input. */
     searchQuery?: string;
     isMultiple?: boolean;
+    /** Visual-only — shows the required asterisk on the label; doesn't block selection or submission. */
     isRequired?: boolean;
     error?: boolean;
+    /** Only rendered when `error` is true — setting this alone shows nothing. */
     errorMessage?: string;
+    /** Hidden whenever `error` is true — mutually exclusive with errorMessage. */
     helperText?: string;
     width?: string | number;
+    /** Only sets the insideSelect segment's height, not the main field's — that's driven by `size`. */
     height?: string | number;
     size?: "xs" | "sm" | "md" | "lg";
     chip?: {
+        /** 0 is falsy and falls back to "no limit" (shows every chip) — pass 1+ to actually cap the count. */
         maxChips?: number;
         maxText?: number;
+        /** Also gates the chip's remove (X) icon — omit it and chips can't be removed via the chip itself. */
         onClick?: (options: Options | Options[]) => void;
     };
     information?: {
         isInformation?: boolean;
         informationMessage?: string;
     };
+    /** Wins over `information.isInformation` when both are set; both this and informationMessage must be truthy to show the icon. */
     isInformation?: boolean;
     informationMessage?: string;
     rightIcon?: {
+        /** Must be a rendered element (`<Icon />`); anything else fails isValidElement and falls back to the toggle chevron. */
         icon?: React.ReactNode;
         onClick?: () => void;
     };
     addNew?: {
+        /** Must be explicitly true — icon/text/onClick alone render nothing. */
         enabled: boolean;
         icon?: React.ReactNode;
         text?: string;
         onClick?: () => void;
     };
     isRemoveAllIcon?: boolean;
+    /** Ignored entirely unless `isMultiple` is also true. */
     isSelectAll?: boolean;
     pagination?: {
+        /** startIndex is 1-based (current options.length + 1), not a 0-based offset. */
         onScroll?: (startIndex: number, limit: number, query: string) => void;
+        /** Also used to guess whether more pages exist (options.length % limit === 0) — an exact-multiple total triggers one extra scroll fetch. */
         limit?: number;
+        /** Set this synchronously while a page request is in flight, or fast scrolling can re-fire onScroll for the same page. */
         scrollLoading?: boolean;
     };
+    /** Not implemented — the option list always renders unvirtualized; use `pagination` to page in large datasets instead. */
     virtualization?: boolean;
     insideSelect?: {
         onSelect?: (options: Options) => void;
+        /** In isMultiple mode, its `id` is stamped onto every newly selected main option as `insideSelectId`. */
         value?: Options;
+        /** The nested picker's own option list — distinct from the top-level `options`, singular name despite being an array. */
         option?: Options[];
         width?: string;
         /** Shown when no value is selected. Defaults to "Select". */
         placeholder?: string;
     };
 };
+/** One selectable option; view, when set, fully replaces the default label rendering for that option's row. */
 export type Options = {
     id: string | number;
     label: string;

package/dist/Components/SegmentedControl/SegmentedControl.d.ts

@@ -0,0 +1,3 @@
+import { SegmentedControlProps } from "./SegmentedControlProps";
+/** Renders role="radiogroup" of role="radio" buttons with roving tabindex, not a native form radio group; shares variant with Toggle/TableToggle (see MODULE.md). */
+export default function SegmentedControl<T extends string = string>({ options, value, onChange, size, isFullWidth, variant, "aria-label": ariaLabel, }: SegmentedControlProps<T>): import("react/jsx-runtime").JSX.Element;