pixelize-design-library 2.4.2-beta.66 → 2.4.2-beta.68

package/dist/Components/Select/SelectPopup.js

@@ -45,8 +45,11 @@ const surfaceRaised_1 = require("../../Theme/tokens/builders/surfaceRaised");
 const focusRing_styles_1 = require("../../Theme/chakra/focusRing.styles");
 const rowStates_1 = require("../../Theme/tokens/builders/rowStates");
 const optionRowInk_1 = require("./optionRowInk");
+const selectRowInk_1 = require("./selectRowInk");
+const selectKeyboardRing_1 = require("./selectKeyboardRing");
 const optionRowSizes_1 = require("../../Theme/tokens/primitives/optionRowSizes");
 const scrollbar_1 = require("../../Theme/tokens/builders/scrollbar");
+const scrollShadow_1 = require("../../Theme/tokens/builders/scrollShadow");
 const controlSizes_1 = require("../../Theme/tokens/primitives/controlSizes");
 const motion_1 = require("../../Theme/tokens/primitives/motion");
 const borderWidths_1 = require("../../Theme/tokens/primitives/borderWidths");
@@ -67,11 +70,13 @@ const DEFAULT_MAX_VISIBLE_CHIPS = 6;
 const VIRTUAL_OVERSCAN = 4;
 const DECORATIVE_CHECKBOX_SX = { "& input": { visibility: "hidden" } };
 const GROUP_HEADER_ESTIMATE_PX = 29;
-const LIST_PADDING_PX = 4;
 const NO_ROW = -1;
 const SELECT_ALL_ROW = -2;
 const CREATE_ROW = -3;
 const FOOTER_ROW = -4;
+const CHECK_SLOT_MIN_PX = 16;
+const SELECT_ALL_RULE_MARGIN_PX = 4;
+const DISABLED_CONTENT_SX = { "& > *": { opacity: selectRowInk_1.SELECT_ROW_DISABLED_CONTENT_OPACITY } };
 const truncateLabel = (label, max) => max !== undefined && label.length > max ? `${label.slice(0, max)}…` : label;
 const asIdSet = (values) => new Set((values !== null && values !== void 0 ? values : []).map((v) => v.toString()));
 /** Regression-guarded id scheme — tickets e2e (`e2e/tests/helpers/selectV2.ts`) resolves it verbatim. */
@@ -80,19 +85,26 @@ const parseRemToPx = (value, fallbackPx) => {
     const match = /^(\d*\.?\d+)rem$/.exec(value);
     return match ? parseFloat(match[1]) * 16 : fallbackPx;
 };
-const OptionRow = react_1.default.memo(function OptionRow({ option, index, listboxId, isSelected, isActive, isMulti, theme, backgrounds, spec, renderOption, onSelect, onActivate, }) {
+const OptionRow = react_1.default.memo(function OptionRow({ option, index, listboxId, isSelected, isActive, isMulti, theme, backgrounds, ink, showRing, spec, renderOption, renderOptionEnd, optionAction, checkPlacement, onSelect, onActivate, }) {
     const isSingleSelected = isSelected && !isMulti;
-    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: optionDomId(listboxId, option.id), "data-index": index, role: "option", "aria-selected": isSelected, "aria-disabled": option.isDisabled, onMouseEnter: () => onActivate(index), onClick: () => onSelect(option), mx: spec.mx, px: spec.px, py: spec.py, minH: spec.minH, borderRadius: "md", cursor: option.isDisabled ? "not-allowed" : "pointer", opacity: option.isDisabled ? 0.4 : 1, display: "flex", alignItems: "center", gap: spec.gap, fontSize: spec.fontSize, fontWeight: (0, optionRowInk_1.optionRowWeight)(isSingleSelected), color: (0, optionRowInk_1.optionRowInk)(theme.colors, isSingleSelected), bg: (0, optionRowInk_1.optionRowFill)(backgrounds, isActive), transition: ROW_TRANSITION, sx: (0, motion_2.reducedMotionSx)(), children: [isMulti ? ((0, jsx_runtime_1.jsx)(react_2.Checkbox, { id: `${optionDomId(listboxId, option.id)}-checkbox`, isChecked: isSelected, isDisabled: option.isDisabled, pointerEvents: "none", tabIndex: -1, sx: DECORATIVE_CHECKBOX_SX })) : null, renderOption ? ((0, jsx_runtime_1.jsx)(react_2.Box, { flex: 1, minW: 0, children: renderOption(option, { isSelected, isActive }) })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [option.icon ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", flexShrink: 0, children: option.icon })) : null, (0, jsx_runtime_1.jsxs)(react_2.Box, { flex: 1, minW: 0, isTruncated: true, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", isTruncated: true, children: option.label }), option.description ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "block", fontSize: spec.descriptionFontSize, color: (0, optionRowInk_1.optionRowDescriptionInk)(theme.colors), isTruncated: true, children: option.description })) : null] })] })), isSingleSelected ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: lucide_react_1.Check, size: spec.iconSize, color: theme.colors.accentText, flexShrink: 0 })) : null] }));
+    const solidDisabledInk = option.isDisabled ? ink.disabled : null;
+    const checkSlotPx = Math.max(CHECK_SLOT_MIN_PX, spec.iconSize);
+    const checkSlot = ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", "aria-hidden": true, display: "inline-flex", justifyContent: "center", flexShrink: 0, width: `${checkSlotPx}px`, children: isSingleSelected ? (0, jsx_runtime_1.jsx)(react_2.Box, { as: lucide_react_1.Check, size: spec.iconSize, color: theme.colors.accentText }) : null }));
+    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: optionDomId(listboxId, option.id), "data-index": index, role: "option", "aria-selected": isSelected, "aria-disabled": option.isDisabled, onMouseEnter: () => onActivate(index), onClick: () => onSelect(option), mx: spec.mx, px: spec.px, py: spec.py, minH: spec.minH, borderRadius: "md", cursor: option.isDisabled ? "not-allowed" : "pointer", display: "flex", alignItems: "center", gap: spec.gap, fontSize: spec.fontSize, fontWeight: (0, optionRowInk_1.optionRowWeight)(isSingleSelected), color: solidDisabledInk !== null && solidDisabledInk !== void 0 ? solidDisabledInk : (isSingleSelected ? ink.selected : ink.rest), bg: (0, selectRowInk_1.selectRowFill)(backgrounds, { isSelected, isActive }), boxShadow: showRing ? (0, selectKeyboardRing_1.keyboardRingShadow)(backgrounds.keyboardRing) : undefined, transition: ROW_TRANSITION, sx: option.isDisabled && !ink.disabled ? { ...(0, motion_2.reducedMotionSx)(), ...DISABLED_CONTENT_SX } : (0, motion_2.reducedMotionSx)(), children: [!isMulti && checkPlacement === "start" ? checkSlot : null, isMulti ? ((0, jsx_runtime_1.jsx)(react_2.Checkbox, { id: `${optionDomId(listboxId, option.id)}-checkbox`, isChecked: isSelected, isDisabled: option.isDisabled, pointerEvents: "none", tabIndex: -1, sx: DECORATIVE_CHECKBOX_SX })) : null, renderOption ? ((0, jsx_runtime_1.jsx)(react_2.Box, { flex: 1, minW: 0, children: renderOption(option, { isSelected, isActive }) })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [option.icon ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", flexShrink: 0, children: option.icon })) : null, (0, jsx_runtime_1.jsxs)(react_2.Box, { flex: 1, minW: 0, isTruncated: true, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", isTruncated: true, children: option.label }), option.description ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "block", fontSize: spec.descriptionFontSize, color: solidDisabledInk !== null && solidDisabledInk !== void 0 ? solidDisabledInk : ink.description, isTruncated: true, children: option.description })) : null] })] })), renderOptionEnd ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", flexShrink: 0, children: renderOptionEnd(option, { isSelected, isActive }) })) : null, optionAction ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", "aria-hidden": true, title: optionAction.label, onMouseDown: (event) => event.preventDefault(), onClick: (event) => {
+                    event.stopPropagation();
+                    optionAction.onAction(option);
+                }, display: "inline-flex", alignItems: "center", justifyContent: "center", flexShrink: 0, cursor: "pointer", color: ink.description, _hover: { color: ink.selected }, children: optionAction.icon })) : null, !isMulti && checkPlacement === "end" ? checkSlot : null] }));
 });
 /** The unified `Select`'s popup mode (`native={false}`) — absorbs SelectV2's behaviour, plus clear/create/groups/virtualization. */
 const SelectPopup = (0, react_1.forwardRef)(function SelectPopup(props, ref) {
     var _a, _b, _c, _d, _e, _f;
-    const { options = [], id, name, placeholder = "Select Option", label, error = false, errorMessage, helperText, isDisabled = false, isReadOnly = false, isRequired = false, isInformation = false, informationMessage, size = controlSizes_1.DEFAULT_CONTROL_SIZE, isSearchable = true, width, formControlStyle, onBlur, onFocus, renderOption, renderValue, maxMenuHeight = "16rem", defaultOpen = false, isLoading = false, loadingText = "Loading...", onLoadMore, hasMore, onSearchChange, searchValue, defaultSearchValue, searchDebounceMs = 0, filterOptions, isClearable = false, onClear, noOptionsMessage, onCreate, createLabel, createWhen = "no-options", footerAction, searchFields, filterOption, isFieldLoading = false, rightIcon, virtualizeAfter, "data-testid": dataTestId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, } = props;
+    const { options = [], id, name, placeholder = "Select Option", label, error = false, errorMessage, helperText, isDisabled = false, isReadOnly = false, isRequired = false, isInformation = false, informationMessage, size = controlSizes_1.DEFAULT_CONTROL_SIZE, isSearchable = true, width, formControlStyle, onBlur, onFocus, renderOption, renderOptionEnd, optionAction, checkPlacement = "end", renderValue, maxMenuHeight = "16rem", defaultOpen = false, isLoading = false, loadingText = "Loading...", onLoadMore, hasMore, onSearchChange, searchValue, defaultSearchValue, searchDebounceMs = 0, filterOptions, isClearable = false, onClear, noOptionsMessage, onCreate, createLabel, createWhen = "no-options", footerAction, searchFields, filterOption, isFieldLoading = false, rightIcon, virtualizeAfter, "data-testid": dataTestId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, } = props;
     const theme = (0, useCustomTheme_1.useCustomTheme)();
     const { colors } = theme;
     const { isOpen, onOpen, onClose } = (0, react_2.useDisclosure)({ defaultIsOpen: defaultOpen });
     const requestExclusiveOpen = (0, useExclusiveOverlay_1.useExclusiveOverlay)(isOpen, onClose);
     const [activeIndex, setActiveIndex] = (0, react_1.useState)(-1);
+    const [isKeyboardNav, setIsKeyboardNav] = (0, react_1.useState)(false);
     const triggerRef = (0, react_1.useRef)(null);
     const mergedTriggerRef = (0, react_2.useMergeRefs)(triggerRef, ref);
     const filterInputRef = (0, react_1.useRef)(null);
@@ -154,6 +166,7 @@ const SelectPopup = (0, react_1.forwardRef)(function SelectPopup(props, ref) {
         if (!isSearchControlled)
             setUncontrolledSearch("");
         setActiveIndex(-1);
+        setIsKeyboardNav(false);
         onBlur === null || onBlur === void 0 ? void 0 : onBlur();
     }, [onClose, onBlur, props.isMulti, isSearchControlled]);
     const handleOpen = () => {
@@ -256,13 +269,14 @@ const SelectPopup = (0, react_1.forwardRef)(function SelectPopup(props, ref) {
         return () => cancelAnimationFrame(frame);
     }, [isOpen, isSearchable]);
     const spec = (0, react_1.useMemo)(() => (0, optionRowSizes_1.optionRowSpec)(size), [size]);
+    const listPaddingPx = parseRemToPx(spec.mx, 6);
     const maxMenuHeightPx = (0, react_1.useMemo)(() => parseRemToPx(maxMenuHeight, 256), [maxMenuHeight]);
     const shouldVirtualize = !!virtualizeAfter && filteredOptions.length > virtualizeAfter;
     const [scrollTop, setScrollTop] = (0, react_1.useState)(0);
     // A description, an avatar or a renderOption row outgrows the spec's single-line height.
     const [rowHeightPx, setRowHeightPx] = (0, react_1.useState)(spec.virtualRowHeightPx);
     const [headerHeightPx, setHeaderHeightPx] = (0, react_1.useState)(GROUP_HEADER_ESTIMATE_PX);
-    const selectAllLeadPx = showSelectAllRow ? rowHeightPx : 0;
+    const selectAllLeadPx = showSelectAllRow ? rowHeightPx + parseInt(borderWidths_1.BORDER_WIDTHS.hairline, 10) + 2 * SELECT_ALL_RULE_MARGIN_PX : 0;
     const windowTop = Math.max(0, scrollTop - selectAllLeadPx);
     const visibleCount = Math.ceil(maxMenuHeightPx / rowHeightPx) + VIRTUAL_OVERSCAN * 2;
     const groupedRows = (0, react_1.useMemo)(() => (hasGroups ? (0, groupedWindow_1.buildGroupedRows)(filteredOptions) : []), [hasGroups, filteredOptions]);
@@ -330,8 +344,8 @@ const SelectPopup = (0, react_1.forwardRef)(function SelectPopup(props, ref) {
                 targetTop = groupedLayout.tops[startsGroup ? rowIndex - 1 : rowIndex];
                 targetBottom = groupedLayout.tops[rowIndex + 1];
             }
-            targetTop += selectAllLeadPx + LIST_PADDING_PX;
-            targetBottom += selectAllLeadPx + LIST_PADDING_PX;
+            targetTop += selectAllLeadPx + listPaddingPx;
+            targetBottom += selectAllLeadPx + listPaddingPx;
             if (targetTop < el.scrollTop) {
                 el.scrollTop = targetTop;
                 setScrollTop(targetTop);
@@ -344,7 +358,7 @@ const SelectPopup = (0, react_1.forwardRef)(function SelectPopup(props, ref) {
             return;
         }
         (_d = (_c = el.querySelector(`[data-index="${activeIndex}"]`)) === null || _c === void 0 ? void 0 : _c.scrollIntoView) === null || _d === void 0 ? void 0 : _d.call(_c, { block: "nearest" });
-    }, [activeIndex, shouldVirtualize, maxMenuHeightPx, rowHeightPx, groupedLayout, groupedRows, selectAllLeadPx, selectAllId, createRowId, footerId]);
+    }, [activeIndex, shouldVirtualize, maxMenuHeightPx, rowHeightPx, groupedLayout, groupedRows, selectAllLeadPx, listPaddingPx, selectAllId, createRowId, footerId]);
     const loadMoreInFlightRef = (0, react_1.useRef)(false);
     const prevOptionsLengthRef = (0, react_1.useRef)(options.length);
     const prevIsLoadingRef = (0, react_1.useRef)(isLoading);
@@ -430,6 +444,8 @@ const SelectPopup = (0, react_1.forwardRef)(function SelectPopup(props, ref) {
     const handleListKeyDown = (event) => {
         var _a, _b;
         const isTextInput = ((_a = event.target) === null || _a === void 0 ? void 0 : _a.tagName) === "INPUT";
+        if (selectKeyboardRing_1.NAVIGATION_KEYS.has(event.key))
+            setIsKeyboardNav(true);
         switch (event.key) {
             case "ArrowDown":
                 event.preventDefault();
@@ -536,8 +552,23 @@ const SelectPopup = (0, react_1.forwardRef)(function SelectPopup(props, ref) {
                 : showCreateRow && (isCreateImplicit || activeIndex === CREATE_ROW)
                     ? createRowId
                     : undefined;
-    const listScrollStyles = (0, react_1.useMemo)(() => (0, scrollbar_1.scrollbarStyles)(colors, "overlay"), [colors]);
-    const rowBackgrounds = (0, react_1.useMemo)(() => (0, rowStates_1.listRowBackgrounds)(colors), [colors]);
+    const listScrollStyles = (0, react_1.useMemo)(() => ({
+        ...(0, scrollbar_1.scrollbarStyles)(colors, "overlay"),
+        ...(0, scrollShadow_1.scrollShadowStylesVertical)(colors.surfaceRaised),
+    }), [colors]);
+    const rowBackgrounds = (0, react_1.useMemo)(() => (0, rowStates_1.selectRowBackgrounds)(colors), [colors]);
+    const rowInks = (0, react_1.useMemo)(() => ({
+        rest: (0, selectRowInk_1.selectRowInk)(colors, false),
+        selected: (0, selectRowInk_1.selectRowInk)(colors, true),
+        description: (0, selectRowInk_1.selectRowDescriptionInk)(colors),
+        disabled: (0, selectRowInk_1.selectRowDisabledInk)(colors),
+    }), [colors]);
+    const filterPlaceholderInk = (0, react_1.useMemo)(() => (0, selectRowInk_1.selectFilterPlaceholderInk)(colors), [colors]);
+    const handlePointerActivate = (0, react_1.useCallback)((index) => {
+        setIsKeyboardNav(false);
+        setActiveIndex(index);
+    }, []);
+    const ringShadowFor = (isActive) => isActive && isKeyboardNav ? (0, selectKeyboardRing_1.keyboardRingShadow)(rowBackgrounds.keyboardRing) : undefined;
     const showChips = !!props.isMulti && !renderValue && selectedOptions.length > 0;
     const chipSize = size === "xs" ? "xs" : "sm";
     const maxVisibleChips = props.isMulti ? ((_a = props.maxVisibleChips) !== null && _a !== void 0 ? _a : DEFAULT_MAX_VISIBLE_CHIPS) : 0;
@@ -580,14 +611,14 @@ const SelectPopup = (0, react_1.forwardRef)(function SelectPopup(props, ref) {
     return ((0, jsx_runtime_1.jsxs)(react_2.FormControl, { isInvalid: error, isDisabled: isDisabled, isReadOnly: isReadOnly, style: formControlStyle, width: width, children: [label && ((0, jsx_runtime_1.jsx)(FormLabel_1.TextLabel, { label: label, id: ids.inputId, isRequired: isRequired, isInformation: isInformation, informationMessage: informationMessage })), (0, jsx_runtime_1.jsxs)(react_2.Popover, { isOpen: isOpen, onClose: () => resetAndClose(), placement: "bottom-start", autoFocus: false, returnFocusOnClose: false, gutter: 4, children: [(0, jsx_runtime_1.jsx)(react_2.PopoverAnchor, { children: (0, jsx_runtime_1.jsxs)(react_2.Box, { as: "div", ref: mergedTriggerRef, ...ids.controlProps, role: "combobox", tabIndex: isDisabled ? -1 : 0, "aria-haspopup": "listbox", "aria-expanded": isOpen, "aria-controls": listboxId, "aria-owns": `${listboxId} ${filterInputId}`, "aria-activedescendant": activeDescendantId, "aria-disabled": isDisabled || undefined, "aria-busy": isFieldLoading || undefined, "data-readonly": isReadOnly || undefined, "aria-required": isRequired || undefined, "aria-label": triggerAriaLabel(), "aria-labelledby": ariaLabelledBy, onClick: handleOpen, onKeyDown: handleTriggerKeyDown, display: "flex", alignItems: "center", justifyContent: "space-between", width: "100%", textAlign: "left", cursor: isDisabled ? "not-allowed" : isReadOnly ? "default" : "pointer", "data-testid": dataTestId, sx: triggerSx, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", flexWrap: showChips ? "wrap" : "nowrap", alignItems: "center", gap: showChips ? 1 : 1.5, minW: 0, flex: 1, isTruncated: !showChips, children: showChips ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [visibleChipOptions.map((option) => ((0, jsx_runtime_1.jsx)(Tag_1.default, { label: truncateLabel(String(option.label), chipMaxLength), size: chipSize, variant: "subtle", icon: canRemoveChips ? lucide_react_1.X : undefined, onIconClick: canRemoveChips ? () => handleSelect(option) : undefined }, option.id))), overflowChipCount > 0 && ((0, jsx_runtime_1.jsx)(Tag_1.default, { label: `+${overflowChipCount}`, size: chipSize, variant: "subtle", colorScheme: "gray" }))] })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [triggerIcon ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", flexShrink: 0, children: triggerIcon })) : null, (0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", isTruncated: true, children: renderValue ? renderValue(selectedOptions) : defaultTriggerContent() })] })) }), showClear && ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "button", type: "button", "aria-label": "Clear selection", onClick: handleClear, display: "inline-flex", alignItems: "center", justifyContent: "center", flexShrink: 0, ml: 2, color: colors.textMuted, _hover: { color: colors.text[700] }, children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { size: controlSizes_1.CONTROL_SIZES[size].iconSize }) })), isFieldLoading ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", "aria-hidden": true, display: "inline-flex", flexShrink: 0, ml: 2, children: (0, jsx_runtime_1.jsx)(react_2.Spinner, { size: "xs", label: "" }) })) : rightIcon ? ("onClick" in rightIcon && isInteractive ? ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "button", type: "button", "aria-label": rightIcon.ariaLabel, onClick: (event) => {
                                         event.stopPropagation();
                                         rightIcon.onClick();
-                                    }, onKeyDown: (event) => event.stopPropagation(), display: "inline-flex", alignItems: "center", justifyContent: "center", flexShrink: 0, ml: 2, color: colors.textMuted, _hover: { color: colors.text[700] }, children: rightIcon.icon })) : ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", "aria-hidden": true, display: "inline-flex", flexShrink: 0, ml: 2, color: colors.textMuted, children: rightIcon.icon }))) : ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", flexShrink: 0, ml: 2, transition: CHEVRON_TRANSITION, transform: isOpen ? "rotate(180deg)" : "rotate(0deg)", color: colors.textMuted, sx: (0, motion_2.reducedMotionSx)(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: controlSizes_1.CONTROL_SIZES[size].iconSize }) }))] }) }), (0, jsx_runtime_1.jsx)(react_2.Portal, { children: (0, jsx_runtime_1.jsxs)(react_2.PopoverContent, { "aria-label": (_d = label !== null && label !== void 0 ? label : ariaLabel) !== null && _d !== void 0 ? _d : placeholder, width: "max-content", minWidth: triggerWidth ? `${triggerWidth}px` : undefined, maxWidth: "min(24rem, calc(100vw - 2rem))", borderRadius: "xl", boxShadow: theme.shadows.lg, overflow: "hidden", onKeyDown: handleListKeyDown, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { p: spec.mx, borderBottom: `${borderWidths_1.BORDER_WIDTHS.hairline} solid ${(0, surfaceRaised_1.raisedRule)(colors)}`, display: isSearchable ? undefined : "none", children: (0, jsx_runtime_1.jsx)(react_2.Input, { ref: filterInputRef, id: filterInputId, size: size, px: spec.px, placeholder: "Type to filter...", value: currentSearch, onChange: handleFilterChange, "aria-activedescendant": activeDescendantId, "aria-controls": listboxId, "aria-label": "Filter options", tabIndex: isSearchable ? undefined : -1 }) }), (0, jsx_runtime_1.jsxs)(react_2.Box, { id: listboxId, ref: listRef, role: "listbox", "aria-label": (_e = label !== null && label !== void 0 ? label : ariaLabel) !== null && _e !== void 0 ? _e : placeholder, "aria-multiselectable": props.isMulti || undefined, "aria-busy": isLoading || undefined, maxH: maxMenuHeight, overflowY: "auto", py: 1, sx: listScrollStyles, onScroll: handleListScroll, children: [filteredOptions.length === 0 && !isLoading && !showCreateRow && ((0, jsx_runtime_1.jsx)(react_2.Box, { mx: spec.mx, px: spec.px, py: spec.py, fontSize: spec.fontSize, color: colors.textMuted, children: noOptionsMessage !== null && noOptionsMessage !== void 0 ? noOptionsMessage : "No Options" })), showSelectAllRow && ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: selectAllId, role: "option", "aria-selected": allFilteredSelected, onClick: handleSelectAll, onMouseEnter: () => setActiveIndex(SELECT_ALL_ROW), mx: spec.mx, px: spec.px, py: spec.py, minH: spec.minH, borderRadius: "md", cursor: "pointer", display: "flex", alignItems: "center", gap: spec.gap, fontSize: spec.fontSize, color: (0, optionRowInk_1.optionRowInk)(colors, false), bg: (0, optionRowInk_1.optionRowFill)(rowBackgrounds, activeIndex === SELECT_ALL_ROW), transition: ROW_TRANSITION, sx: (0, motion_2.reducedMotionSx)(), children: [(0, jsx_runtime_1.jsx)(react_2.Checkbox, { isChecked: allFilteredSelected, pointerEvents: "none", tabIndex: -1, sx: DECORATIVE_CHECKBOX_SX }), allFilteredSelected ? "Unselect All" : "Select All"] })), hasGroups
+                                    }, onKeyDown: (event) => event.stopPropagation(), display: "inline-flex", alignItems: "center", justifyContent: "center", flexShrink: 0, ml: 2, color: colors.textMuted, _hover: { color: colors.text[700] }, children: rightIcon.icon })) : ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", "aria-hidden": true, display: "inline-flex", flexShrink: 0, ml: 2, color: colors.textMuted, children: rightIcon.icon }))) : ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-flex", flexShrink: 0, ml: 2, transition: CHEVRON_TRANSITION, transform: isOpen ? "rotate(180deg)" : "rotate(0deg)", color: colors.textMuted, sx: (0, motion_2.reducedMotionSx)(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: controlSizes_1.CONTROL_SIZES[size].iconSize }) }))] }) }), (0, jsx_runtime_1.jsx)(react_2.Portal, { children: (0, jsx_runtime_1.jsxs)(react_2.PopoverContent, { "aria-label": (_d = label !== null && label !== void 0 ? label : ariaLabel) !== null && _d !== void 0 ? _d : placeholder, width: "max-content", minWidth: triggerWidth ? `${triggerWidth}px` : undefined, maxWidth: "min(24rem, calc(100vw - 2rem))", borderRadius: "xl", boxShadow: theme.shadows.lg, overflow: "hidden", onKeyDown: handleListKeyDown, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { p: spec.mx, borderBottom: `${borderWidths_1.BORDER_WIDTHS.hairline} solid ${(0, surfaceRaised_1.raisedRule)(colors)}`, display: isSearchable ? undefined : "none", children: (0, jsx_runtime_1.jsx)(react_2.Input, { ref: filterInputRef, id: filterInputId, size: size, px: spec.px, placeholder: "Type to filter...", _placeholder: filterPlaceholderInk ? { color: filterPlaceholderInk } : undefined, value: currentSearch, onChange: handleFilterChange, "aria-activedescendant": activeDescendantId, "aria-controls": listboxId, "aria-label": "Filter options", tabIndex: isSearchable ? undefined : -1 }) }), (0, jsx_runtime_1.jsxs)(react_2.Box, { id: listboxId, ref: listRef, role: "listbox", "aria-label": (_e = label !== null && label !== void 0 ? label : ariaLabel) !== null && _e !== void 0 ? _e : placeholder, "aria-multiselectable": props.isMulti || undefined, "aria-busy": isLoading || undefined, maxH: maxMenuHeight, overflowY: "auto", py: spec.mx, sx: listScrollStyles, onScroll: handleListScroll, children: [filteredOptions.length === 0 && !isLoading && !showCreateRow && ((0, jsx_runtime_1.jsx)(react_2.Box, { mx: spec.mx, px: spec.px, py: spec.py, fontSize: spec.fontSize, color: colors.textMuted, children: noOptionsMessage !== null && noOptionsMessage !== void 0 ? noOptionsMessage : "No Options" })), showSelectAllRow && ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: selectAllId, role: "option", "aria-selected": allFilteredSelected, onClick: handleSelectAll, onMouseEnter: () => handlePointerActivate(SELECT_ALL_ROW), mx: spec.mx, px: spec.px, py: spec.py, minH: spec.minH, borderRadius: "md", cursor: "pointer", display: "flex", alignItems: "center", gap: spec.gap, fontSize: spec.fontSize, color: rowInks.rest, bg: (0, selectRowInk_1.selectRowFill)(rowBackgrounds, { isSelected: false, isActive: activeIndex === SELECT_ALL_ROW }), boxShadow: ringShadowFor(activeIndex === SELECT_ALL_ROW), transition: ROW_TRANSITION, sx: (0, motion_2.reducedMotionSx)(), children: [(0, jsx_runtime_1.jsx)(react_2.Checkbox, { isChecked: allFilteredSelected, pointerEvents: "none", tabIndex: -1, sx: DECORATIVE_CHECKBOX_SX }), allFilteredSelected ? "Unselect All" : "Select All"] })), showSelectAllRow && ((0, jsx_runtime_1.jsx)(react_2.Box, { role: "presentation", mx: spec.mx, my: `${SELECT_ALL_RULE_MARGIN_PX}px`, height: borderWidths_1.BORDER_WIDTHS.hairline, bg: (0, surfaceRaised_1.raisedRule)(colors) })), hasGroups
                                             ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [topPadPx > 0 && (0, jsx_runtime_1.jsx)(react_2.Box, { height: `${topPadPx}px` }), renderedGroupedRows.map((row) => {
                                                         var _a;
-                                                        return row.kind === "header" ? ((0, jsx_runtime_1.jsx)(react_2.Box, { "data-group-header": shouldVirtualize ? "" : undefined, mx: spec.mx, px: spec.px, pt: 2, pb: 1, fontSize: "xs-minus", fontWeight: 600, textTransform: "uppercase", letterSpacing: "0.03em", color: colors.textMuted, children: row.group }, row.key)) : ((0, jsx_runtime_1.jsx)(OptionRow, { option: row.option, index: row.index, listboxId: listboxId, isSelected: selectedIds.has(row.option.id.toString()), isActive: row.index === activeIndex, isMulti: (_a = props.isMulti) !== null && _a !== void 0 ? _a : false, theme: theme, backgrounds: rowBackgrounds, spec: spec, renderOption: renderOption, onSelect: handleSelect, onActivate: setActiveIndex }, row.key));
+                                                        return row.kind === "header" ? ((0, jsx_runtime_1.jsx)(react_2.Box, { "data-group-header": shouldVirtualize ? "" : undefined, mx: spec.mx, px: spec.px, pt: 2, pb: 1, fontSize: "xs-minus", fontWeight: 600, textTransform: "uppercase", letterSpacing: "0.03em", color: colors.textMuted, children: row.group }, row.key)) : ((0, jsx_runtime_1.jsx)(OptionRow, { option: row.option, index: row.index, listboxId: listboxId, isSelected: selectedIds.has(row.option.id.toString()), isActive: row.index === activeIndex, isMulti: (_a = props.isMulti) !== null && _a !== void 0 ? _a : false, theme: theme, backgrounds: rowBackgrounds, ink: rowInks, showRing: isKeyboardNav && row.index === activeIndex, spec: spec, renderOption: renderOption, renderOptionEnd: renderOptionEnd, optionAction: optionAction, checkPlacement: checkPlacement, onSelect: handleSelect, onActivate: handlePointerActivate }, row.key));
                                                     }), bottomPadPx > 0 && (0, jsx_runtime_1.jsx)(react_2.Box, { height: `${bottomPadPx}px` })] }))
                                             : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [topPadPx > 0 && (0, jsx_runtime_1.jsx)(react_2.Box, { height: `${topPadPx}px` }), renderedOptions.map((option, i) => {
                                                         var _a;
-                                                        return ((0, jsx_runtime_1.jsx)(OptionRow, { option: option, index: startIndex + i, listboxId: listboxId, isSelected: selectedIds.has(option.id.toString()), isActive: startIndex + i === activeIndex, isMulti: (_a = props.isMulti) !== null && _a !== void 0 ? _a : false, theme: theme, backgrounds: rowBackgrounds, spec: spec, renderOption: renderOption, onSelect: handleSelect, onActivate: setActiveIndex }, option.id));
-                                                    }), bottomPadPx > 0 && (0, jsx_runtime_1.jsx)(react_2.Box, { height: `${bottomPadPx}px` })] })), showCreateRow && ((0, jsx_runtime_1.jsx)(react_2.Box, { id: createRowId, role: "option", "aria-selected": false, "data-index": -1, onClick: handleCreate, mx: spec.mx, px: spec.px, py: spec.py, minH: spec.minH, borderRadius: "md", cursor: "pointer", fontSize: spec.fontSize, fontWeight: 600, color: colors.primary[600], bg: activeDescendantId === createRowId ? rowBackgrounds.active : "transparent", children: createLabel ? createLabel(currentSearch.trim()) : `Create "${currentSearch.trim()}"` })), isLoading && ((0, jsx_runtime_1.jsxs)(react_2.Box, { mx: spec.mx, px: spec.px, py: spec.py, display: "flex", alignItems: "center", gap: spec.gap, fontSize: spec.fontSize, color: colors.textMuted, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: "xs" }), loadingText] })), footerAction && ((0, jsx_runtime_1.jsx)(react_2.Box, { id: footerId, role: "option", "aria-selected": false, onClick: handleFooterAction, onMouseEnter: () => setActiveIndex(FOOTER_ROW), position: "sticky", bottom: -1, pt: 1, bg: colors.surfaceRaised, borderTop: `${borderWidths_1.BORDER_WIDTHS.hairline} solid ${(0, surfaceRaised_1.raisedRule)(colors)}`, children: (0, jsx_runtime_1.jsxs)(react_2.Box, { mx: spec.mx, px: spec.px, py: spec.py, minH: spec.minH, borderRadius: "md", cursor: "pointer", display: "flex", alignItems: "center", gap: spec.gap, fontSize: spec.fontSize, fontWeight: 500, color: colors.accentText, bg: activeIndex === FOOTER_ROW ? rowBackgrounds.active : "transparent", children: [(_f = footerAction.icon) !== null && _f !== void 0 ? _f : (0, jsx_runtime_1.jsx)(lucide_react_1.Plus, { size: spec.iconSize }), footerAction.label] }) }))] })] }) })] }), hiddenValues.map((value) => ((0, jsx_runtime_1.jsx)("input", { type: "hidden", name: name, value: value }, value))), (0, jsx_runtime_1.jsx)(FieldMessage_1.default, { error: error, errorMessage: errorMessage, helperText: helperText, helperId: ids.helperId, errorId: ids.errorId })] }));
+                                                        return ((0, jsx_runtime_1.jsx)(OptionRow, { option: option, index: startIndex + i, listboxId: listboxId, isSelected: selectedIds.has(option.id.toString()), isActive: startIndex + i === activeIndex, isMulti: (_a = props.isMulti) !== null && _a !== void 0 ? _a : false, theme: theme, backgrounds: rowBackgrounds, ink: rowInks, showRing: isKeyboardNav && startIndex + i === activeIndex, spec: spec, renderOption: renderOption, renderOptionEnd: renderOptionEnd, optionAction: optionAction, checkPlacement: checkPlacement, onSelect: handleSelect, onActivate: handlePointerActivate }, option.id));
+                                                    }), bottomPadPx > 0 && (0, jsx_runtime_1.jsx)(react_2.Box, { height: `${bottomPadPx}px` })] })), showCreateRow && ((0, jsx_runtime_1.jsx)(react_2.Box, { id: createRowId, role: "option", "aria-selected": false, "data-index": -1, onClick: handleCreate, mx: spec.mx, px: spec.px, py: spec.py, minH: spec.minH, borderRadius: "md", cursor: "pointer", fontSize: spec.fontSize, fontWeight: 600, color: colors.primary[600], bg: activeDescendantId === createRowId ? rowBackgrounds.active : "transparent", boxShadow: ringShadowFor(activeDescendantId === createRowId), children: createLabel ? createLabel(currentSearch.trim()) : `Create "${currentSearch.trim()}"` })), isLoading && ((0, jsx_runtime_1.jsxs)(react_2.Box, { mx: spec.mx, px: spec.px, py: spec.py, display: "flex", alignItems: "center", gap: spec.gap, fontSize: spec.fontSize, color: colors.textMuted, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: "xs" }), loadingText] })), footerAction && ((0, jsx_runtime_1.jsx)(react_2.Box, { id: footerId, role: "option", "aria-selected": false, onClick: handleFooterAction, onMouseEnter: () => handlePointerActivate(FOOTER_ROW), position: "sticky", bottom: `-${spec.mx}`, pt: 1, bg: colors.surfaceRaised, borderTop: `${borderWidths_1.BORDER_WIDTHS.hairline} solid ${(0, surfaceRaised_1.raisedRule)(colors)}`, children: (0, jsx_runtime_1.jsxs)(react_2.Box, { mx: spec.mx, px: spec.px, py: spec.py, minH: spec.minH, borderRadius: "md", cursor: "pointer", display: "flex", alignItems: "center", gap: spec.gap, fontSize: spec.fontSize, fontWeight: 500, color: colors.accentText, bg: activeIndex === FOOTER_ROW ? rowBackgrounds.active : "transparent", boxShadow: ringShadowFor(activeIndex === FOOTER_ROW), children: [(_f = footerAction.icon) !== null && _f !== void 0 ? _f : (0, jsx_runtime_1.jsx)(lucide_react_1.Plus, { size: spec.iconSize }), footerAction.label] }) }))] })] }) })] }), hiddenValues.map((value) => ((0, jsx_runtime_1.jsx)("input", { type: "hidden", name: name, value: value }, value))), (0, jsx_runtime_1.jsx)(FieldMessage_1.default, { error: error, errorMessage: errorMessage, helperText: helperText, helperId: ids.helperId, errorId: ids.errorId })] }));
 });
 exports.default = SelectPopup;

package/dist/Components/Select/SelectProps.d.ts

@@ -3,7 +3,9 @@ import type { ReactNode } from "react";
 import type { ControlSize } from "../../Theme/tokens/primitives/controlSizes";
 /** Select option; icon/description/group/isDisabled are popup-mode extras, all optional and additive. */
 export type OptionProp = {
+    /** Unique value of the option: what `value` / `defaultValue` select by and what native mode emits as the `<option>` value. */
     id: string | number;
+    /** Text shown in the row and the trigger; the default filter matches against it. */
     label: string | number;
     /** Popup mode only — leading icon/avatar for this option's row (and the trigger, when selected). */
     icon?: ReactNode;
@@ -15,12 +17,15 @@ export type OptionProp = {
     group?: string;
 };
 type SelectCommonProps = {
+    /** Choices in display order; options that share a `group` should sit next to each other. */
     options: OptionProp[];
     /** Renders a themed popup instead of a real `<select>` when false. Defaults to true — today's `Select`, unchanged. */
     native?: boolean;
     /** DOM id of the control; auto-generated when omitted, so the label and messages always associate. */
     id?: string;
+    /** Native: the `<select>` name. Popup: submits the selection through hidden input(s), one per value when multi. */
     name?: string;
+    /** Label above the field; its `for` points at the control. */
     label?: string;
     /** Native: the built-in placeholder `<option>`. Popup: trigger text when nothing is selected. Defaults to "Select Option". */
     placeholder?: string;
@@ -36,8 +41,11 @@ type SelectCommonProps = {
     errorMessage?: string;
     /** Hint under the field; hidden while `error` is true. */
     helperText?: string;
+    /** Disables the field; the popup cannot open. */
     isDisabled?: boolean;
+    /** Shows the value but ignores changes; the popup never opens. */
     isReadOnly?: boolean;
+    /** Label asterisk and `aria-required`; the popup never blocks an empty submit. */
     isRequired?: boolean;
     /** Shows an info icon beside the label; needs `label` and `informationMessage` too. */
     isInformation?: boolean;
@@ -45,16 +53,25 @@ type SelectCommonProps = {
     informationMessage?: string;
     /** Inline style on the wrapping FormControl (label + control + message). */
     formControlStyle?: React.CSSProperties;
+    /** Accessible name when there is no `label`; the popup forwards it to the trigger. */
     "aria-label"?: string;
+    /** Id of an element that names the field; the popup forwards it to the trigger. */
     "aria-labelledby"?: string;
     /** Popup mode only — forwarded to the trigger, the same node as `role="combobox"`. */
     "data-testid"?: string;
+    /** Native mode only — field style: `outline` (default), `filled`, `flushed` or `unstyled`; inert (dev-warned) when `native` is false. */
     variant?: ChakraNativeSelectProps["variant"];
+    /** Native mode only — forwarded to Chakra's Select; inert (dev-warned) when `native` is false. */
     colorScheme?: ChakraNativeSelectProps["colorScheme"];
+    /** Native mode only — replaces the dropdown arrow; inert (dev-warned) when `native` is false. */
     icon?: ChakraNativeSelectProps["icon"];
+    /** Native mode only — background of the `<select>`; inert (dev-warned) when `native` is false. */
     bg?: ChakraNativeSelectProps["bg"];
+    /** Native mode only — border colour of the `<select>`; inert (dev-warned) when `native` is false. */
     borderColor?: ChakraNativeSelectProps["borderColor"];
+    /** Native mode only — text colour of the `<select>`; inert (dev-warned) when `native` is false. */
     color?: ChakraNativeSelectProps["color"];
+    /** Native mode only — border colour while `error`; inert (dev-warned) when `native` is false. */
     errorBorderColor?: ChakraNativeSelectProps["errorBorderColor"];
     /** Native mode only — inline style on the `<select>` element itself. */
     selectStyle?: React.CSSProperties;
@@ -90,10 +107,14 @@ type SelectCommonProps = {
     isFieldLoading?: boolean;
     /** Trailing slot replacing the chevron; with `onClick` it renders a button (so `ariaLabel` is required) that does not toggle the popup. Popup mode only. */
     rightIcon?: {
+        /** Node shown in place of the chevron. */
         icon: ReactNode;
     } | {
+        /** Node shown in place of the chevron. */
         icon: ReactNode;
+        /** Makes the icon a button that calls this without toggling the popup. */
         onClick: () => void;
+        /** Accessible name of the icon button. */
         ariaLabel: string;
     };
     /** Empty-list message. Native mode stringifies it (plain `<option>` text); popup mode accepts any node. */
@@ -107,6 +128,22 @@ type SelectCommonProps = {
         isSelected: boolean;
         isActive: boolean;
     }) => ReactNode;
+    /** Non-interactive content between the row and its check, e.g. a badge; receives isSelected/isActive. Popup mode only. */
+    renderOptionEnd?: (option: OptionProp, state: {
+        isSelected: boolean;
+        isActive: boolean;
+    }) => ReactNode;
+    /** One pointer-only row action: aria-hidden, tabIndex -1, and a click never selects the row. Popup mode only. */
+    optionAction?: {
+        /** Node shown in the action button. */
+        icon: ReactNode;
+        /** Hover title of the button; the button itself is hidden from assistive tech, so offer the action another way too. */
+        label: string;
+        /** Called with the row's option when the button is clicked. */
+        onAction: (option: OptionProp) => void;
+    };
+    /** Single-select check position: "end" (default) trails the row, "start" sits in the leading column the multi checkbox uses. Popup mode only. */
+    checkPlacement?: "end" | "start";
     /** Custom trigger content once a value is selected. Popup mode only. */
     renderValue?: (selected: OptionProp[]) => ReactNode;
     /** Shows a "Create …" row when the filter matches no option; fires with the trimmed query. Popup mode only. */
@@ -117,8 +154,11 @@ type SelectCommonProps = {
     createWhen?: "no-options" | "no-exact-match";
     /** A persistent last row ("Add new…") shown whatever the filter; `onSelect` gets the trimmed query and the popup closes. Popup mode only. */
     footerAction?: {
+        /** Text of the footer row. */
         label: ReactNode;
+        /** Called with the trimmed filter text when the row is chosen; the popup then closes. */
         onSelect: (query: string) => void;
+        /** Icon before the label; a plus icon when omitted. */
         icon?: ReactNode;
     };
     /** Max popup height before the option list scrolls. Defaults to "16rem". Popup mode only. */
@@ -130,10 +170,11 @@ type SelectCommonProps = {
 };
 /** Single-select arm of `SelectFieldProps`; `isMulti` false/absent discriminates it from the multi variant. */
 export type SelectSingleProps = SelectCommonProps & {
+    /** False or absent selects this single-select variant. */
     isMulti?: false;
-    /** Controlled selected option id. */
+    /** Controlled selected option id; native mode stays uncontrolled until a defined `value` has been passed (`""` shows the placeholder). */
     value?: string | number;
-    /** Seeds an uncontrolled selection; ignored once `value` is passed (even `""`). */
+    /** Seeds an uncontrolled selection in native and popup mode; ignored once `value` is passed (even `""`). */
     defaultValue?: string | number;
     /** Canonical change callback. Never fires for the native placeholder; gate a reset behind `isClearable`. */
     onChange: (selectedOption: OptionProp | undefined) => void;
@@ -142,8 +183,11 @@ export type SelectSingleProps = SelectCommonProps & {
 export type SelectMultiProps = SelectCommonProps & {
     /** Multi-select requires the popup — rendered even if `native` is left true, with a dev warning. */
     isMulti: true;
+    /** Controlled selected option ids. */
     value?: (string | number)[];
+    /** Seeds an uncontrolled selection; ignored once `value` is passed. */
     defaultValue?: (string | number)[];
+    /** Called with the full selection after each toggle or chip removal. */
     onChange: (selectedOptions: OptionProp[]) => void;
     /** Chips shown before the rest collapse into a "+N" chip. Defaults to 6. */
     maxVisibleChips?: number;

package/dist/Components/Select/selectKeyboardRing.d.ts

@@ -0,0 +1,2 @@
+export declare const NAVIGATION_KEYS: Set<string>;
+export declare const keyboardRingShadow: (ring: string) => string;

package/dist/Components/Select/selectKeyboardRing.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyboardRingShadow = exports.NAVIGATION_KEYS = void 0;
+const borderWidths_1 = require("../../Theme/tokens/primitives/borderWidths");
+exports.NAVIGATION_KEYS = new Set(["ArrowDown", "ArrowUp", "Home", "End", "PageUp", "PageDown"]);
+const keyboardRingShadow = (ring) => `inset 0 0 0 ${borderWidths_1.BORDER_WIDTHS.hairline} ${ring}`;
+exports.keyboardRingShadow = keyboardRingShadow;

package/dist/Components/Select/selectRowInk.d.ts

@@ -0,0 +1,14 @@
+import { type SelectRowBackgrounds } from "../../Theme/tokens/builders/rowStates";
+import type { PaletteProps } from "../../Theme/tokens/types";
+export declare const SELECT_ROW_DISABLED_CONTENT_OPACITY = 0.55;
+export declare const selectRowInk: (colors: PaletteProps, isSingleSelected: boolean) => string;
+export declare const selectRowDescriptionInk: (colors: PaletteProps) => string;
+/** Solid ink for a disabled row's content in light; dark dims content by opacity instead (null). */
+export declare const selectRowDisabledInk: (colors: PaletteProps) => string | null;
+/** Placeholder of the popup's filter input in light; dark keeps the shared placeholder ink (null). */
+export declare const selectFilterPlaceholderInk: (colors: PaletteProps) => string | null;
+/** Cursor and selection each paint a rung; the stacked state paints the third. */
+export declare const selectRowFill: (rows: SelectRowBackgrounds, state: {
+    isSelected: boolean;
+    isActive: boolean;
+}) => string;

package/dist/Components/Select/selectRowInk.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectRowFill = exports.selectFilterPlaceholderInk = exports.selectRowDisabledInk = exports.selectRowDescriptionInk = exports.selectRowInk = exports.SELECT_ROW_DISABLED_CONTENT_OPACITY = void 0;
+const accentText_1 = require("../../Theme/tokens/builders/accentText");
+const outlineRung_1 = require("../../Theme/tokens/builders/outlineRung");
+const rowStates_1 = require("../../Theme/tokens/builders/rowStates");
+const optionRowInk_1 = require("./optionRowInk");
+exports.SELECT_ROW_DISABLED_CONTENT_OPACITY = 0.55;
+const NEUTRAL_INK_STEPS = {
+    label: 12.8,
+    selected: 15.4,
+    description: 7,
+    disabled: 3.6,
+    placeholder: 4.6,
+};
+// NOTE: light is a brand-free grey ladder off the panel; dark keeps the shared inks.
+const neutralInk = (colors, role) => (0, outlineRung_1.neutralStep)(colors.surfaceRaised, NEUTRAL_INK_STEPS[role]);
+const isDarkPanel = (colors) => (0, accentText_1.isDarkCanvas)(colors.surfaceRaised);
+const selectRowInk = (colors, isSingleSelected) => {
+    if (isDarkPanel(colors))
+        return (0, optionRowInk_1.optionRowInk)(colors, isSingleSelected);
+    return neutralInk(colors, isSingleSelected ? "selected" : "label");
+};
+exports.selectRowInk = selectRowInk;
+const selectRowDescriptionInk = (colors) => isDarkPanel(colors)
+    ? (0, outlineRung_1.liftToContrast)(colors.textMuted, (0, rowStates_1.selectRowBackgrounds)(colors).selectedActive, accentText_1.AA_NORMAL_TEXT)
+    : neutralInk(colors, "description");
+exports.selectRowDescriptionInk = selectRowDescriptionInk;
+/** Solid ink for a disabled row's content in light; dark dims content by opacity instead (null). */
+const selectRowDisabledInk = (colors) => isDarkPanel(colors) ? null : neutralInk(colors, "disabled");
+exports.selectRowDisabledInk = selectRowDisabledInk;
+/** Placeholder of the popup's filter input in light; dark keeps the shared placeholder ink (null). */
+const selectFilterPlaceholderInk = (colors) => isDarkPanel(colors) ? null : neutralInk(colors, "placeholder");
+exports.selectFilterPlaceholderInk = selectFilterPlaceholderInk;
+/** Cursor and selection each paint a rung; the stacked state paints the third. */
+const selectRowFill = (rows, state) => {
+    if (state.isActive)
+        return state.isSelected ? rows.selectedActive : rows.active;
+    return state.isSelected ? rows.selected : "transparent";
+};
+exports.selectRowFill = selectRowFill;

package/dist/Components/SelectSearch/SelectSearch.js

@@ -22,6 +22,8 @@ const useCustomTheme_1 = require("../../Theme/useCustomTheme");
 const surfaceRaised_1 = require("../../Theme/tokens/builders/surfaceRaised");
 const rowStates_1 = require("../../Theme/tokens/builders/rowStates");
 const optionRowInk_1 = require("../Select/optionRowInk");
+const selectKeyboardRing_1 = require("../Select/selectKeyboardRing");
+const selectRowInk_1 = require("../Select/selectRowInk");
 const useExclusiveOverlay_1 = require("../../Hooks/useExclusiveOverlay");
 const lucide_react_1 = require("lucide-react");
 const activationKey_1 = require("../Common/activationKey");
@@ -29,8 +31,12 @@ const useOutsideMouseDown_1 = require("../../Hooks/useOutsideMouseDown");
 const ROW_TRANSITION = (0, motion_1.transitionFor)(["background-color"]);
 const RenderOptions = ({ isOptionLoading, filteredOptions, loadingText, handleOptionClick, isProfile, isColorOptions, isOptionSelected, activeIndex, optionRefs, size, isMultipleSelect, }) => {
     const theme = (0, useCustomTheme_1.useCustomTheme)();
-    const rowBackgrounds = (0, react_1.useMemo)(() => (0, rowStates_1.listRowBackgrounds)(theme.colors), [theme.colors]);
+    const rowBackgrounds = (0, react_1.useMemo)(() => (0, rowStates_1.selectRowBackgrounds)(theme.colors), [theme.colors]);
     const spec = (0, optionRowSizes_1.optionRowSpec)(size);
+    const keyboardRing = {
+        outline: "2px solid transparent",
+        boxShadow: (0, selectKeyboardRing_1.keyboardRingShadow)(rowBackgrounds.keyboardRing),
+    };
     if (isOptionLoading) {
         return ((0, jsx_runtime_1.jsxs)(react_2.VStack, { py: 2, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: "sm", color: theme.colors.accentText }), (0, jsx_runtime_1.jsx)(react_2.Text, { color: theme.colors.accentText, children: loadingText })] }));
     }
@@ -41,7 +47,7 @@ const RenderOptions = ({ isOptionLoading, filteredOptions, loadingText, handleOp
                 const isActive = index === activeIndex;
                 return ((0, jsx_runtime_1.jsxs)(react_2.Box, { as: "button", type: "button", ref: (el) => {
                         optionRefs.current[index] = el;
-                    }, role: "option", "aria-selected": selected, tabIndex: isActive ? 0 : -1, w: `calc(100% - 2 * ${spec.mx})`, minH: spec.minH, textAlign: "left", border: "none", fontFamily: "inherit", bg: "transparent", mx: spec.mx, px: spec.px, py: spec.py, borderRadius: optionRowSizes_1.OPTION_ROW_RADIUS, fontSize: spec.fontSize, cursor: "pointer", color: (0, optionRowInk_1.optionRowInk)(theme.colors, isSingleSelected), fontWeight: (0, optionRowInk_1.optionRowWeight)(isSingleSelected), transition: ROW_TRANSITION, sx: (0, motion_2.reducedMotionSx)(), ...(0, optionRowInk_1.optionRowCursorSx)(rowBackgrounds), onClick: () => handleOptionClick(option), onKeyDown: (0, activationKey_1.onActivationKey)(() => handleOptionClick(option)), display: "flex", alignItems: "center", gap: spec.gap, children: [isProfile && ((0, jsx_runtime_1.jsx)(react_2.Box, { children: (0, jsx_runtime_1.jsx)(Avatar_1.default, { size: spec.avatarSize, name: option.label.toLocaleUpperCase(), src: option.profileUrl ? option.profileUrl : undefined }) })), isColorOptions && ((0, jsx_runtime_1.jsx)(react_2.Box, { width: "0.8rem", height: "0.8rem", content: "", backgroundColor: option === null || option === void 0 ? void 0 : option.color, borderRadius: "full" })), (0, jsx_runtime_1.jsxs)(react_2.Box, { flex: 1, minW: 0, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { children: option.label }), option.email && ((0, jsx_runtime_1.jsx)(react_2.Box, { fontSize: spec.descriptionFontSize, color: (0, optionRowInk_1.optionRowDescriptionInk)(theme.colors), children: option.email }))] }), isSingleSelected && ((0, jsx_runtime_1.jsx)(react_2.Box, { as: lucide_react_1.Check, size: spec.iconSize, color: theme.colors.accentText, flexShrink: 0 }))] }, option.id));
+                    }, role: "option", "aria-selected": selected, tabIndex: isActive ? 0 : -1, w: `calc(100% - 2 * ${spec.mx})`, minH: spec.minH, textAlign: "left", border: "none", fontFamily: "inherit", bg: selected ? rowBackgrounds.selected : "transparent", mx: spec.mx, px: spec.px, py: spec.py, borderRadius: optionRowSizes_1.OPTION_ROW_RADIUS, fontSize: spec.fontSize, cursor: "pointer", color: (0, selectRowInk_1.selectRowInk)(theme.colors, isSingleSelected), fontWeight: (0, optionRowInk_1.optionRowWeight)(isSingleSelected), transition: ROW_TRANSITION, sx: (0, motion_2.reducedMotionSx)(), _hover: { bg: selected ? rowBackgrounds.selectedActive : rowBackgrounds.active }, _focus: { bg: selected ? rowBackgrounds.selectedActive : rowBackgrounds.active }, _focusVisible: keyboardRing, onClick: () => handleOptionClick(option), onKeyDown: (0, activationKey_1.onActivationKey)(() => handleOptionClick(option)), display: "flex", alignItems: "center", gap: spec.gap, children: [isProfile && ((0, jsx_runtime_1.jsx)(react_2.Box, { children: (0, jsx_runtime_1.jsx)(Avatar_1.default, { size: spec.avatarSize, name: option.label.toLocaleUpperCase(), src: option.profileUrl ? option.profileUrl : undefined }) })), isColorOptions && ((0, jsx_runtime_1.jsx)(react_2.Box, { width: "0.8rem", height: "0.8rem", content: "", backgroundColor: option === null || option === void 0 ? void 0 : option.color, borderRadius: "full" })), (0, jsx_runtime_1.jsxs)(react_2.Box, { flex: 1, minW: 0, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { children: option.label }), option.email && ((0, jsx_runtime_1.jsx)(react_2.Box, { fontSize: spec.descriptionFontSize, color: (0, selectRowInk_1.selectRowDescriptionInk)(theme.colors), children: option.email }))] }), isSingleSelected && ((0, jsx_runtime_1.jsx)(react_2.Box, { as: lucide_react_1.Check, size: spec.iconSize, color: theme.colors.accentText, flexShrink: 0 }))] }, option.id));
             }) }));
     }
     return ((0, jsx_runtime_1.jsx)(react_2.Text, { px: 4, py: 2, color: theme.colors.textMuted, children: "No options found" }));

package/dist/Components/SelectSearch/SelectSearchProps.d.ts

@@ -1,6 +1,7 @@
 import type { ControlSize } from "../../Theme/tokens/primitives/controlSizes";
 /** Prefer `Select` with `native={false}` for new work — not a drop-in: its combobox is the text input itself. See COMPONENT-GOTCHAS.md ("Which select component"). */
 export type SelectSearchProps = {
+    /** Choices; filtered locally by label as the user types. */
     options: selectOptions[];
     /** @deprecated Never read — the search input always renders. */
     isSearchEnabled?: boolean;
@@ -12,8 +13,11 @@ export type SelectSearchProps = {
     onOptionMultiSelect?: (option: selectOptions[]) => void;
     /** Fires on every keystroke, undebounced; local label filtering runs regardless. */
     inputOnchange: (value: string | number) => void;
+    /** Id of the text input; the label's `for` and the message ids derive from it. Auto-generated when omitted. */
     id?: string;
+    /** Name attribute of the text input, so a form submits the typed text, not the selection. */
     name?: string;
+    /** Label above the input. */
     label?: string;
     /** Inline style on the text input. */
     inputStyle?: React.CSSProperties;
@@ -66,9 +70,14 @@ export type SelectSearchProps = {
 };
 /** Option shape for SelectSearch; `email`/`profileUrl` back `isProfile` rows, `color` backs `isColorOptions` rows. */
 export type selectOptions = {
+    /** Unique key of the option. */
     id: string;
+    /** Row text; the local filter matches against it, and its initials back the avatar when `profileUrl` is missing. */
     label: string;
+    /** Muted second line under the label. */
     email?: string;
+    /** Avatar image in `isProfile` rows. */
     profileUrl?: string;
+    /** Fill of the dot in `isColorOptions` rows. */
     color?: string;
 };

package/dist/Components/SelectV2/SelectV2Props.d.ts

@@ -2,7 +2,9 @@ import type { ReactNode } from "react";
 import type { ControlSize } from "../../Theme/tokens/primitives/controlSizes";
 /** SelectV2 option shape; adds optional `icon`/`description`/`isDisabled` beyond the plain id/label pair. */
 export type OptionProp = {
+    /** Unique value of the option; what `value` selects by. */
     id: string | number;
+    /** Text shown in the row and the trigger; the search filter matches against it. */
     label: string | number;
     /** Optional leading icon/avatar for this option's row (and the trigger, when selected). */
     icon?: ReactNode;
@@ -14,6 +16,7 @@ export type OptionProp = {
 /** sm/md/lg subset kept for existing importers; the `size` prop takes the full `ControlSize` scale. */
 export type SelectV2Size = "sm" | "md" | "lg";
 type SelectV2CommonProps = {
+    /** Choices in display order. */
     options: OptionProp[];
     /** DOM id of the trigger; the label's `for` and the message ids derive from it. Auto-generated when omitted. */
     id?: string;
@@ -21,6 +24,7 @@ type SelectV2CommonProps = {
     name?: string;
     /** Trigger text when nothing is selected. Defaults to "Select Option". */
     placeholder?: string;
+    /** Label above the trigger. */
     label?: string;
     /** Marks the field invalid and swaps `helperText` for `errorMessage`. */
     error?: boolean;
@@ -28,6 +32,7 @@ type SelectV2CommonProps = {
     errorMessage?: string;
     /** Hint under the field; hidden while `error` is true. */
     helperText?: string;
+    /** Disables the trigger; the popup cannot open. */
     isDisabled?: boolean;
     /** Shows the value but never opens; exposed as `aria-readonly`. */
     isReadOnly?: boolean;
@@ -72,6 +77,7 @@ type SelectV2CommonProps = {
 /** Single-select arm of `SelectV2Props`; `isMulti` false/absent discriminates it from the multi variant. */
 /** @deprecated Use `SelectSingleProps` (`native={false}`). */
 export type SelectV2SingleProps = SelectV2CommonProps & {
+    /** False or absent selects this single-select variant. */
     isMulti?: false;
     /** Selected option `id`; compared as strings, so `1` matches `"1"`. */
     value?: string | number;
@@ -81,6 +87,7 @@ export type SelectV2SingleProps = SelectV2CommonProps & {
 /** Multi-select arm of `SelectV2Props`; `isMulti: true` discriminates it and makes `value` an array. */
 /** @deprecated Use `SelectMultiProps` (`native={false}`). */
 export type SelectV2MultiProps = SelectV2CommonProps & {
+    /** True makes `value` an array and `onChange` receive the full selection. */
     isMulti: true;
     /** Selected option ids; ids with no matching option are dropped from the display. */
     value?: (string | number)[];

package/dist/Components/SideBar/SecondaryBar.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
 import { SecondaryBarProps } from "./SideBarProps";
+/** Secondary flyout panel beside the main rail, listing the active menu's `secondaryItems`; collapses to icons. */
 declare const SecondaryBar: React.FC<SecondaryBarProps>;
 export default SecondaryBar;

package/dist/Components/SideBar/SecondaryBar.js

@@ -72,6 +72,7 @@ const ExpandedItem = ({ item, isActive, itemFontSize, onItemClick }) => {
         }, borderLeft: "2px solid", borderLeftColor: isActive ? theme.colors.sidebar.activeIcon : "transparent", transition: sidebarMotion_1.SIDEBAR_BG_TRANSITION, sx: (0, sidebarFocus_1.sidebarFocusStyles)(theme.colors), children: [(0, jsx_runtime_1.jsxs)(react_2.Flex, { align: "center", gap: 2, flex: "1", minW: 0, overflow: "hidden", children: [(0, jsx_runtime_1.jsx)(react_2.Icon, { as: item.icon, fontSize: sidebarScale_1.SIDEBAR_ROW.iconSize, flexShrink: 0, color: isActive ? activeAccent.icon : theme.colors.sidebar.mutedIcon, _groupHover: isActive ? undefined : { color: theme.colors.white }, transition: sidebarMotion_1.SIDEBAR_INK_TRANSITION }), (0, jsx_runtime_1.jsx)(react_2.Box, { flex: "1", minW: 0, children: (0, jsx_runtime_1.jsx)(OverflowTooltipText_1.default, { placement: "right", maxWidth: "100%", fontSize: itemFontSize, fontWeight: isActive ? 600 : 500, color: isActive ? activeAccent.label : theme.colors.white, _groupHover: isActive ? undefined : { color: theme.colors.white }, as: "p", children: item.title }) })] }), item.locked ? ((0, jsx_runtime_1.jsx)(react_2.Icon, { as: lucide_react_1.LockKeyhole, fontSize: "sm", flexShrink: 0, color: theme.colors.sidebar.mutedIcon })) : (badgeVal != null && ((0, jsx_runtime_1.jsx)(react_2.Badge, { ...softBadge(theme.colors, colorScheme, (0, sidebarAccent_1.sidebarRowPeak)(theme.colors.sidebar.background[500])), fontSize: "xs", variant: variant, borderRadius: radius, children: badgeVal })))] }));
     return item.locked && item.lockedReason ? ((0, jsx_runtime_1.jsx)(ToolTip_1.default, { label: item.lockedReason, placement: "top", children: row })) : (row);
 };
+/** Secondary flyout panel beside the main rail, listing the active menu's `secondaryItems`; collapses to icons. */
 const SecondaryBar = ({ items = [], defaultCollapsed = true, collapsedWidth = "3.5rem", expandedWidth = "10rem", headerFontSize = sidebarScale_1.SIDEBAR_ROW.fontSize, itemFontSize = sidebarScale_1.SIDEBAR_ROW.fontSize, selected, onItemClick, title, icon, }) => {
     const theme = (0, useCustomTheme_1.useCustomTheme)();
     const activeAccent = (0, sidebarAccentColors_1.getSidebarActiveAccent)(theme.colors);

package/dist/Components/SideBar/SideBar.d.ts

@@ -1,2 +1,3 @@
 import { SidebarProps } from "./SideBarProps";
+/** Left navigation rail: collapsible inline from `lg`, a slide-in overlay below it, with menus, pinned shortcuts, submenus, a secondary flyout and a footer. */
 export default function Sidebar({ menus, activeMenu, handleMenuClick, handleSecondaryNavClick, toggle, changeToggle, logo, companyName, companySubtitle, user, isDisableAddNew, onAddNewClick, selectedSubMenu, selectedSecondaryItem, isLoading, loadingLines, open, otherApps, mobileOpen, onMobileClose, mobileNav, onToggleMobileNav, peekOpen, onPeekEnd, pinnedItems, pinnedLabel, onUnpin, activePinnedId, pinnedLimit, pinnedLabels, collapseTransition, autoCollapse, }: SidebarProps): import("react/jsx-runtime").JSX.Element;

package/dist/Components/SideBar/SideBar.js

@@ -128,6 +128,7 @@ const FooterControls = ({ toggle, overlay, mobileNav, onToggleCollapse, onToggle
     return shell((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(ControlCell, { onClick: onToggleCollapse, ariaLabel: toggle ? "Expand sidebar" : undefined, label: toggle ? undefined : "Collapse", children: toggle ? ((0, jsx_runtime_1.jsx)(lucide_react_1.ArrowRightToLine, { size: 14, color: iconColor })) : ((0, jsx_runtime_1.jsx)(lucide_react_1.ArrowLeftToLine, { size: 14, color: iconColor })) }), onToggleMobileNav && ((0, jsx_runtime_1.jsx)(ControlCell, { onClick: onToggleMobileNav, ariaLabel: toggle ? "Show sidebar in overlay mode" : undefined, label: toggle ? undefined : "Hide", children: (0, jsx_runtime_1.jsx)(lucide_react_1.Maximize2, { size: 14, color: iconColor }) }))] }));
 };
 // --- Main Sidebar component ---
+/** Left navigation rail: collapsible inline from `lg`, a slide-in overlay below it, with menus, pinned shortcuts, submenus, a secondary flyout and a footer. */
 function Sidebar({ menus, activeMenu, handleMenuClick, handleSecondaryNavClick, toggle, changeToggle, logo, companyName, companySubtitle, user, isDisableAddNew = false, onAddNewClick, selectedSubMenu, selectedSecondaryItem, isLoading, loadingLines, open = true, otherApps, mobileOpen = false, onMobileClose, mobileNav = false, onToggleMobileNav, peekOpen = false, onPeekEnd, pinnedItems, pinnedLabel, onUnpin, activePinnedId, pinnedLimit, pinnedLabels, collapseTransition = { speed: "base" }, autoCollapse = true, }) {
     var _a, _b;
     const theme = (0, useCustomTheme_1.useCustomTheme)();