pixelize-design-library 2.4.2-beta.67 → 2.4.2-beta.69

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

@@ -5,27 +5,42 @@ export type PermissionKey = "read" | "create" | "edit" | "delete" | "import" | "
 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 cell; for the Automation module it is the only cell shown and reflects `automation`. */
     read: boolean;
+    /** Whether the Create cell is checked. */
     create: boolean;
+    /** Whether the Edit cell is checked. */
     edit: boolean;
+    /** Whether the Delete cell is checked. */
     delete: boolean;
+    /** Whether the Import cell is checked; only rendered when `permissionKeys` includes it. */
     import?: boolean;
+    /** Whether the Export cell is checked; only rendered when `permissionKeys` includes it. */
     export?: boolean;
+    /** Flag the Automation module row reads and toggles instead of the per-column booleans. */
     automation?: boolean;
 };
 /** One row in the roles list — the same shape is passed back into onEditRole/onViewRole as the selected role. */
 export type RoleData = {
+    /** Shown in the list, truncated with an ellipsis when long. */
     roleName: string;
+    /** Shown as given in the Created By column. */
     createdBy: string;
+    /** Shown as given, unformatted, in the Created Time column. */
     created_at: string;
+    /** The role's matrix rows; not rendered in the list, handed back via `onEditRole`/`onViewRole` to prefill `permissions`. */
     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;
+    /** Pass-through for the consumer to prefill its form. */
     makeSuperAdmin?: boolean;
+    /** Pass-through for the consumer to prefill its form. */
     automation?: boolean;
+    /** Pass-through for the consumer to prefill its form. */
     trackLocation?: boolean;
+    /** Pass-through for the consumer to prefill its form. */
     show_records?: boolean;
 };
 /** Top-level switch: "list" renders the roles table, "form" renders the create/edit/view role form. */
@@ -37,38 +52,71 @@ export type RolesPermissionMode = "create" | "edit" | "view";
  * key has a sensible English default so the component works standalone.
  */
 export type RolesPermissionLabels = {
+    /** Heading of the roles list. */
     title?: string;
+    /** Prefix of the role-count badge ("Total Roles: 4"). */
     totalRoles?: string;
+    /** Text of the new-role button. */
     newRole?: string;
+    /** Serial-number column header. */
     sNo?: string;
+    /** Role name column header. */
     roleNameColumn?: string;
+    /** Created-by column header. */
     createdBy?: string;
+    /** Created-time column header. */
     createdTime?: string;
+    /** Actions column header. */
     actions?: string;
+    /** Empty-state title when there are no roles. */
     noRoles?: string;
+    /** Name and tooltip of the row View icon. */
     view?: string;
+    /** Name and tooltip of the row Edit icon. */
     edit?: string;
+    /** Name and tooltip of the row Delete icon, and the confirm button of the delete dialog. */
     delete?: string;
+    /** Heading of the role details card in the form. */
     roleInformation?: string;
+    /** Label of the role name input. */
     roleName?: string;
+    /** Placeholder of the role name input. */
     roleNamePlaceholder?: string;
+    /** Label of the super-admin checkbox. */
     enableAllPermissions?: string;
+    /** Label of the track-location checkbox. */
     trackLocation?: string;
+    /** Label of the show-all-records checkbox. */
     showAllUserRecords?: string;
+    /** Heading of the permission matrix card. */
     permissionSettings?: string;
+    /** Module column header of the matrix. */
     moduleName?: string;
+    /** Read column header. */
     read?: string;
+    /** Create column header. */
     create?: string;
+    /** Edit column header. */
     editPermission?: string;
+    /** Delete column header. */
     deletePermission?: string;
+    /** Import column header. */
     importPermission?: string;
+    /** Export column header. */
     exportPermission?: string;
+    /** Shown in the matrix when `permissions` is empty. */
     noPermissions?: string;
+    /** Text of the form Cancel button and the delete dialog cancel button. */
     cancel?: string;
+    /** Save button text when not `isEditing`. */
     saveChanges?: string;
+    /** Save button text when `isEditing`. */
     updateChanges?: string;
+    /** Tooltip on the disabled role name input in view mode. */
     readOnly?: string;
+    /** Title of the delete confirmation dialog. */
     deleteRole?: string;
+    /** Body text of the delete confirmation dialog. */
     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). */
@@ -79,6 +127,7 @@ export interface RolesPermissionProps {
     mode?: RolesPermissionMode;
     /** Roles list data. */
     roles: RoleData[];
+    /** Shows skeleton rows instead of the table and hides the role-count badge. */
     isRolesLoading?: boolean;
     /** Permission matrix rows for the form view. */
     permissions: Permission[];
@@ -86,10 +135,13 @@ export interface RolesPermissionProps {
     permissionKeys?: PermissionKey[];
     /** Form field values — fully controlled, no internal state; edits are invisible without the matching handler below. */
     roleName: string;
+    /** Error text under the role name input; any non-empty value also marks it invalid. */
     roleNameError?: string;
     /** Toggling this does not itself grant matrix permissions — it's cosmetic until the consumer applies that logic. */
     isSuperAdmin: boolean;
+    /** Checked state of the track-location checkbox. */
     isTrackLocation: boolean;
+    /** Checked state of the show-all-records checkbox. */
     isShowRecords: boolean;
     /** Whether the role is being edited (changes the Save button label). */
     isEditing?: boolean;
@@ -97,7 +149,9 @@ export interface RolesPermissionProps {
     isSaving?: boolean;
     /** List actions. */
     onNewRole?: () => void;
+    /** Fires with the role when its View icon is pressed. */
     onViewRole?: (role: RoleData) => void;
+    /** Fires with the role when its Edit icon is pressed. */
     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;
@@ -105,13 +159,17 @@ export interface RolesPermissionProps {
     onBack?: () => void;
     /** Form actions. */
     onRoleNameChange?: (value: string) => void;
+    /** Fires with the new checked state of the enable-all-permissions checkbox. */
     onToggleSuperAdmin?: (checked: boolean) => void;
+    /** Fires with the new checked state of the track-location checkbox. */
     onToggleTrackLocation?: (checked: boolean) => void;
+    /** Fires with the new checked state of the show-all-records checkbox. */
     onToggleShowRecords?: (checked: boolean) => void;
     /** Fires with key "automation" (not "read") for a module named "automation" — see Permission.module. */
     onPermissionChange?: (module: string, key: PermissionKey) => void;
+    /** Fires when the Save or Update button is pressed; the footer is hidden in view mode. */
     onSave?: () => void;
-    /** Header back icon renders only when set; the footer Cancel button always renders and no-ops without it. */
+    /** Header back icon renders only when set; the footer Cancel button renders outside view mode and no-ops without it. */
     onCancelForm?: () => void;
     /** App-specific sections rendered under the roles list (e.g. ModuleDelete, SignInActivity). */
     footerSlot?: ReactNode;

package/dist/Components/SearchSelect/SearchSelect.js

@@ -48,6 +48,8 @@ const planeStep_1 = require("../../Theme/tokens/builders/planeStep");
 const rowStates_1 = require("../../Theme/tokens/builders/rowStates");
 const optionRowSizes_1 = require("../../Theme/tokens/primitives/optionRowSizes");
 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 FieldMessage_1 = __importDefault(require("../Common/FieldMessage"));
 const useFieldIds_1 = require("../Common/useFieldIds");
@@ -79,9 +81,9 @@ const normalizeMultiValue = (val) => {
     return [];
 };
 const DECORATIVE_CHECKBOX_SX = { pointerEvents: "none", "& input": { visibility: "hidden" } };
-const OptionRow = react_1.default.memo(function OptionRow({ option, index, optionId, isSelected, isActive, isMultiple, spec, colors, rowBackgrounds, checkboxSize, onSelect, onActivate, }) {
+const OptionRow = react_1.default.memo(function OptionRow({ option, index, optionId, isSelected, isActive, showRing, isMultiple, spec, colors, rowBackgrounds, checkboxSize, onSelect, onActivate, }) {
     const singleSelected = isSelected && !isMultiple;
-    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: optionId, "data-index": index, role: "option", "aria-selected": isSelected, mx: spec.mx, py: spec.py, px: spec.px, minH: spec.minH, borderRadius: optionRowSizes_1.OPTION_ROW_RADIUS, cursor: "pointer", bg: (0, optionRowInk_1.optionRowFill)(rowBackgrounds, isActive), onClick: () => onSelect(option), onMouseEnter: () => onActivate(index), display: "flex", alignItems: "center", gap: spec.gap, color: (0, optionRowInk_1.optionRowInk)(colors, singleSelected), 
+    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: optionId, "data-index": index, role: "option", "aria-selected": isSelected, mx: spec.mx, py: spec.py, px: spec.px, minH: spec.minH, borderRadius: optionRowSizes_1.OPTION_ROW_RADIUS, cursor: "pointer", bg: (0, selectRowInk_1.selectRowFill)(rowBackgrounds, { isSelected, isActive }), boxShadow: showRing ? (0, selectKeyboardRing_1.keyboardRingShadow)(rowBackgrounds.keyboardRing) : undefined, onClick: () => onSelect(option), onMouseEnter: () => onActivate(index), display: "flex", alignItems: "center", gap: spec.gap, color: (0, selectRowInk_1.selectRowInk)(colors, singleSelected), 
         // `view` is consumer JSX with no size of its own; it inherited the 16px body font.
         fontSize: spec.fontSize, fontWeight: (0, optionRowInk_1.optionRowWeight)(singleSelected), children: [isMultiple && ((0, jsx_runtime_1.jsx)(Checkbox_1.default, { isChecked: isSelected, sx: DECORATIVE_CHECKBOX_SX, size: checkboxSize })), option.view ? ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: option.view })) : ((0, jsx_runtime_1.jsx)(react_2.Text, { flex: 1, minW: 0, isTruncated: true, children: option.label })), singleSelected && ((0, jsx_runtime_1.jsx)(react_2.Box, { as: lucide_react_1.Check, size: spec.iconSize, color: colors.accentText, flexShrink: 0 }))] }));
 });
@@ -117,7 +119,8 @@ const SearchSelect = ({ id, label, options, onChange, onSelect, onSearch, isOpti
         width: 0,
     });
     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 insideRowBackgrounds = (0, react_1.useMemo)(() => (0, rowStates_1.listRowBackgrounds)(theme.colors), [theme.colors]);
     // NOTE: inset — the trigger sits flush in the field and the menu clips overflow.
     const insideFocusRing = {
         outline: "2px solid transparent",
@@ -131,6 +134,7 @@ const SearchSelect = ({ id, label, options, onChange, onSelect, onSearch, isOpti
     const selectAllId = `${baseId}-select-all`;
     const addNewId = `${baseId}-add-new`;
     const [activeIndex, setActiveIndex] = (0, react_1.useState)(searchSelectNav_1.NO_ROW);
+    const [isKeyboardNav, setIsKeyboardNav] = (0, react_1.useState)(false);
     const pendingFocusRestoreRef = (0, react_1.useRef)(false);
     // NOTE: the ARIA host follows real focus; opening from a button doesn't move it.
     const [focusedTrigger, setFocusedTrigger] = (0, react_1.useState)(null);
@@ -284,7 +288,12 @@ const SearchSelect = ({ id, label, options, onChange, onSelect, onSearch, isOpti
         setCustomSelectOpen(false);
         setIsOpen(true);
     };
+    const handlePointerActivate = (0, react_1.useCallback)((index) => {
+        setIsKeyboardNav(false);
+        setActiveIndex(index);
+    }, []);
     const moveActive = (delta) => {
+        setIsKeyboardNav(true);
         setActiveIndex((prev) => (0, searchSelectNav_1.stepRow)(rowLayout, prev, delta));
     };
     const restoreFocus = () => {
@@ -322,12 +331,14 @@ const SearchSelect = ({ id, label, options, onChange, onSelect, onSearch, isOpti
             case "Home":
                 if (isOpen && (0, searchSelectNav_1.firstRow)(rowLayout) !== searchSelectNav_1.NO_ROW && !isTextInputTarget) {
                     e.preventDefault();
+                    setIsKeyboardNav(true);
                     setActiveIndex((0, searchSelectNav_1.firstRow)(rowLayout));
                 }
                 break;
             case "End":
                 if (isOpen && (0, searchSelectNav_1.lastRow)(rowLayout) !== searchSelectNav_1.NO_ROW && !isTextInputTarget) {
                     e.preventDefault();
+                    setIsKeyboardNav(true);
                     setActiveIndex((0, searchSelectNav_1.lastRow)(rowLayout));
                 }
                 break;
@@ -375,6 +386,7 @@ const SearchSelect = ({ id, label, options, onChange, onSelect, onSearch, isOpti
     (0, react_1.useEffect)(() => {
         if (!isOpen) {
             setActiveIndex(searchSelectNav_1.NO_ROW);
+            setIsKeyboardNav(false);
             return;
         }
         const layout = { optionCount: filteredOptions.length, hasSelectAll: hasSelectAllRow, hasAddNew: hasAddNewRow };
@@ -651,7 +663,7 @@ const SearchSelect = ({ id, label, options, onChange, onSelect, onSearch, isOpti
                                 }, 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.textMuted, 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: CHEVRON_TRANSITION, 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, role: "listbox", "aria-label": insidePlaceholder, onKeyDown: handleInsideMenuKeyDown, onFocus: stopFocusBubbling, onBlur: stopFocusBubbling, position: "fixed", style: { top: `${customSelectPos.top}px`, left: `${customSelectPos.left}px` }, zIndex: zIndices_1.default.popoverNested, bg: theme.colors.surfaceRaised, border: `${borderWidths_1.BORDER_WIDTHS.hairline} solid`, borderColor: theme.colors.boxborder[200], borderRadius: "xl", boxShadow: theme.shadows.lg, minW: `${customSelectPos.width}px`, maxW: "20rem", py: 1, overflow: "hidden", children: (_c = insideSelect.option) === null || _c === void 0 ? void 0 : _c.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: spec.gap, minH: spec.minH, py: spec.py, px: spec.px, fontSize: spec.fontSize, fontWeight: (0, optionRowInk_1.optionRowWeight)(selected), color: (0, optionRowInk_1.optionRowInk)(theme.colors, selected), bg: "transparent", ...(0, optionRowInk_1.optionRowCursorSx)(rowBackgrounds), cursor: "pointer", role: "option", "aria-selected": selected, tabIndex: -1, _focusVisible: insideFocusRing, onClick: (e) => {
+                                                return ((0, jsx_runtime_1.jsxs)(react_2.Box, { display: "flex", alignItems: "center", justifyContent: "space-between", gap: spec.gap, minH: spec.minH, py: spec.py, px: spec.px, fontSize: spec.fontSize, fontWeight: (0, optionRowInk_1.optionRowWeight)(selected), color: (0, optionRowInk_1.optionRowInk)(theme.colors, selected), bg: "transparent", ...(0, optionRowInk_1.optionRowCursorSx)(insideRowBackgrounds), cursor: "pointer", role: "option", "aria-selected": selected, tabIndex: -1, _focusVisible: insideFocusRing, onClick: (e) => {
                                                         e.stopPropagation();
                                                         handleCustomSelect(item);
                                                     }, children: [(0, jsx_runtime_1.jsx)(react_2.Text, { isTruncated: true, children: item.label }), selected && ((0, jsx_runtime_1.jsx)(lucide_react_1.Check, { size: spec.iconSize, color: theme.colors.accentText }))] }, item.id));
@@ -690,6 +702,6 @@ const SearchSelect = ({ id, label, options, onChange, onSelect, onSearch, isOpti
                         top: `${dropdownPos.top}px`,
                         left: `${dropdownPos.left}px`,
                         width: `${dropdownPos.width}px`,
-                    }, zIndex: zIndices_1.default.popover, maxH: "20rem", borderWidth: 1, borderColor: theme.colors.boxborder[200], borderRadius: "xl", overflow: "hidden", bg: theme.colors.surfaceRaised, boxShadow: theme.shadows.lg, display: "flex", flexDirection: "column", children: [hasSelectAllRow && ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: selectAllId, role: "option", "aria-selected": allFilteredSelected, bg: activeIndex === searchSelectNav_1.SELECT_ALL_ROW ? rowBackgrounds.active : undefined, py: spec.py, px: spec.px, minH: spec.minH, cursor: "pointer", onClick: handleSelectAll, display: "flex", alignItems: "center", gap: spec.gap, color: theme.colors.text[700], borderBottom: `${borderWidths_1.BORDER_WIDTHS.hairline} solid ${(0, surfaceRaised_1.raisedRule)(theme.colors)}`, children: [(0, jsx_runtime_1.jsx)(Checkbox_1.default, { isChecked: allFilteredSelected, sx: DECORATIVE_CHECKBOX_SX, size: s.checkboxSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: spec.fontSize, children: allFilteredSelected ? "Unselect All" : "Select All" })] })), (0, jsx_runtime_1.jsx)(react_2.Box, { ref: optionsListRef, flex: "1", overflowY: "auto", onScroll: handleScroll, maxH: "15rem", py: 1, borderBottom: `${borderWidths_1.BORDER_WIDTHS.hairline} solid`, borderColor: (0, surfaceRaised_1.raisedRule)(theme.colors), children: isOptionLoading && filteredOptions.length === 0 ? ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: spec.py, px: spec.px, display: "flex", alignItems: "center", gap: spec.gap, minH: spec.minH, color: theme.colors.textMuted, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: s.spinnerSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: spec.fontSize, children: loadingText })] })) : !isOptionLoading && filteredOptions.length === 0 ? ((0, jsx_runtime_1.jsx)(react_2.Text, { p: 3, fontSize: spec.fontSize, 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.jsx)(OptionRow, { option: option, index: index, optionId: getOptionId(index), isSelected: isSelected(option.id), isActive: index === activeIndex, isMultiple: isMultiple, spec: spec, colors: theme.colors, rowBackgrounds: rowBackgrounds, checkboxSize: s.checkboxSize, onSelect: selectOption, onActivate: setActiveIndex }, option.id))), ((pagination === null || pagination === void 0 ? void 0 : pagination.scrollLoading) || (isOptionLoading && filteredOptions.length > 0)) && ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: spec.py, px: spec.px, display: "flex", alignItems: "center", justifyContent: "center", gap: spec.gap, minH: spec.minH, color: theme.colors.textMuted, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: s.spinnerSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: spec.fontSize, children: loadingText })] }))] })) }), (addNew === null || addNew === void 0 ? void 0 : addNew.enabled) && ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: addNewId, role: "option", "aria-selected": false, py: spec.py, px: spec.px, borderTop: `${borderWidths_1.BORDER_WIDTHS.hairline} solid`, borderColor: (0, surfaceRaised_1.raisedRule)(theme.colors), bg: activeIndex === searchSelectNav_1.ADD_NEW_ROW ? rowBackgrounds.active : theme.colors.surfaceRaised, display: "flex", alignItems: "center", gap: spec.gap, color: theme.colors.accentText, fontWeight: 500, minH: spec.minH, 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: spec.fontSize, children: addNew.text || "Add New" })] }))] }) })), (0, jsx_runtime_1.jsx)(FieldMessage_1.default, { error: error, errorMessage: errorMessage, helperText: helperText, helperId: ids.helperId, errorId: ids.errorId })] }));
+                    }, zIndex: zIndices_1.default.popover, maxH: "20rem", borderWidth: 1, borderColor: theme.colors.boxborder[200], borderRadius: "xl", overflow: "hidden", bg: theme.colors.surfaceRaised, boxShadow: theme.shadows.lg, display: "flex", flexDirection: "column", children: [hasSelectAllRow && ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: selectAllId, role: "option", "aria-selected": allFilteredSelected, bg: (0, selectRowInk_1.selectRowFill)(rowBackgrounds, { isSelected: false, isActive: activeIndex === searchSelectNav_1.SELECT_ALL_ROW }), boxShadow: isKeyboardNav && activeIndex === searchSelectNav_1.SELECT_ALL_ROW ? (0, selectKeyboardRing_1.keyboardRingShadow)(rowBackgrounds.keyboardRing) : undefined, py: spec.py, px: spec.px, minH: spec.minH, cursor: "pointer", onClick: handleSelectAll, onMouseEnter: () => handlePointerActivate(searchSelectNav_1.SELECT_ALL_ROW), display: "flex", alignItems: "center", gap: spec.gap, color: (0, selectRowInk_1.selectRowInk)(theme.colors, false), borderBottom: `${borderWidths_1.BORDER_WIDTHS.hairline} solid ${(0, surfaceRaised_1.raisedRule)(theme.colors)}`, children: [(0, jsx_runtime_1.jsx)(Checkbox_1.default, { isChecked: allFilteredSelected, sx: DECORATIVE_CHECKBOX_SX, size: s.checkboxSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: spec.fontSize, children: allFilteredSelected ? "Unselect All" : "Select All" })] })), (0, jsx_runtime_1.jsx)(react_2.Box, { ref: optionsListRef, flex: "1", overflowY: "auto", onScroll: handleScroll, maxH: "15rem", py: 1, borderBottom: `${borderWidths_1.BORDER_WIDTHS.hairline} solid`, borderColor: (0, surfaceRaised_1.raisedRule)(theme.colors), children: isOptionLoading && filteredOptions.length === 0 ? ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: spec.py, px: spec.px, display: "flex", alignItems: "center", gap: spec.gap, minH: spec.minH, color: theme.colors.textMuted, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: s.spinnerSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: spec.fontSize, children: loadingText })] })) : !isOptionLoading && filteredOptions.length === 0 ? ((0, jsx_runtime_1.jsx)(react_2.Text, { p: 3, fontSize: spec.fontSize, 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.jsx)(OptionRow, { option: option, index: index, optionId: getOptionId(index), isSelected: isSelected(option.id), isActive: index === activeIndex, showRing: isKeyboardNav && index === activeIndex, isMultiple: isMultiple, spec: spec, colors: theme.colors, rowBackgrounds: rowBackgrounds, checkboxSize: s.checkboxSize, onSelect: selectOption, onActivate: handlePointerActivate }, option.id))), ((pagination === null || pagination === void 0 ? void 0 : pagination.scrollLoading) || (isOptionLoading && filteredOptions.length > 0)) && ((0, jsx_runtime_1.jsxs)(react_2.Box, { py: spec.py, px: spec.px, display: "flex", alignItems: "center", justifyContent: "center", gap: spec.gap, minH: spec.minH, color: theme.colors.textMuted, children: [(0, jsx_runtime_1.jsx)(react_2.Spinner, { size: s.spinnerSize }), (0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: spec.fontSize, children: loadingText })] }))] })) }), (addNew === null || addNew === void 0 ? void 0 : addNew.enabled) && ((0, jsx_runtime_1.jsxs)(react_2.Box, { id: addNewId, role: "option", "aria-selected": false, py: spec.py, px: spec.px, borderTop: `${borderWidths_1.BORDER_WIDTHS.hairline} solid`, borderColor: (0, surfaceRaised_1.raisedRule)(theme.colors), bg: activeIndex === searchSelectNav_1.ADD_NEW_ROW ? rowBackgrounds.active : theme.colors.surfaceRaised, boxShadow: isKeyboardNav && activeIndex === searchSelectNav_1.ADD_NEW_ROW ? (0, selectKeyboardRing_1.keyboardRingShadow)(rowBackgrounds.keyboardRing) : undefined, display: "flex", alignItems: "center", gap: spec.gap, color: theme.colors.accentText, fontWeight: 500, minH: spec.minH, 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: spec.fontSize, children: addNew.text || "Add New" })] }))] }) })), (0, jsx_runtime_1.jsx)(FieldMessage_1.default, { error: error, errorMessage: errorMessage, helperText: helperText, helperId: ids.helperId, errorId: ids.errorId })] }));
 };
 exports.default = SearchSelect;

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

@@ -1,7 +1,9 @@
 /** value's shape must match isMultiple (array vs single object) — a mismatch normalizes to no selection, not an error. */
 /** Prefer `Select` with `native={false}` for new work — not yet a drop-in; see COMPONENT-GOTCHAS.md ("Which select component"). */
 export type SearchSelectProps = {
+    /** Base DOM id of the trigger; listbox and option ids derive from it. Auto-generated when omitted. */
     id?: string;
+    /** Visible label above the field; omit it and set `aria-label` for a labelless field. */
     label?: string;
     /** Accessible name for a labelless field; falls back to the visible label when both are set. */
     "aria-label"?: string;
@@ -29,6 +31,7 @@ export type SearchSelectProps = {
     isMultiple?: boolean;
     /** Visual-only — shows the required asterisk on the label; doesn't block selection or submission. */
     isRequired?: boolean;
+    /** Marks the field invalid with the error border and ring; `errorMessage` text shows only while true. */
     error?: boolean;
     /** Only rendered when `error` is true — setting this alone shows nothing. */
     errorMessage?: string;
@@ -42,6 +45,7 @@ export type SearchSelectProps = {
     size?: "xs" | "sm" | "md" | "lg";
     /** Blocks opening, typing, chip removal and clearing; renders the shared disabled field look. */
     isDisabled?: boolean;
+    /** Tuning for selected-value chips; only applies when `isMultiple` is true. */
     chip?: {
         /** Chips shown before a "+N" chip; `0` shows only the count. */
         maxChips?: number;
@@ -57,13 +61,16 @@ export type SearchSelectProps = {
     };
     /** Wins over `information.isInformation` when both are set; both this and informationMessage must be truthy to show the icon. */
     isInformation?: boolean;
+    /** Tooltip text on the label info icon; needs `isInformation` and a `label` to appear. */
     informationMessage?: string;
+    /** Replaces the trailing toggle chevron with a custom icon; ignored while `isLoading` shows the spinner. */
     rightIcon?: {
         /** Must be a rendered element (`<Icon />`); anything else fails isValidElement and falls back to the toggle chevron. */
         icon?: React.ReactNode;
         /** Fires on custom-icon click; the click also bubbles to the field and opens the menu. */
         onClick?: () => void;
     };
+    /** Adds a footer "add new" row below the options; nothing renders unless `enabled` is true. */
     addNew?: {
         /** Must be explicitly true — icon/text/onClick alone render nothing. */
         enabled: boolean;
@@ -78,6 +85,7 @@ export type SearchSelectProps = {
     isRemoveAllIcon?: boolean;
     /** Ignored entirely unless `isMultiple` is also true. */
     isSelectAll?: boolean;
+    /** Infinite-scroll paging: `onScroll` fires near the list end while more rows are expected. */
     pagination?: {
         /** startIndex is 1-based (current options.length + 1), not a 0-based offset. */
         onScroll?: (startIndex: number, limit: number, query: string) => void;
@@ -92,6 +100,7 @@ export type SearchSelectProps = {
     };
     /** @deprecated Not implemented — the option list never virtualizes; page large datasets with `pagination` instead. */
     virtualization?: boolean;
+    /** Renders a second nested picker inside the field (e.g. a country code) beside the main input. */
     insideSelect?: {
         /** Fires with the picked nested option; the nested picker is controlled via `insideSelect.value`. */
         onSelect?: (options: Options) => void;
@@ -108,7 +117,10 @@ export type SearchSelectProps = {
 /** One selectable option; view, when set, fully replaces the default label rendering for that option's row. */
 /** Prefer `Select` with `native={false}` for new work — not yet a drop-in; see COMPONENT-GOTCHAS.md ("Which select component"). */
 export type Options = {
+    /** Unique key; selected state and chip removal are matched by it. */
     id: string | number;
+    /** Text shown in the row and chip, and the only text the search box filters on. */
     label: string;
+    /** Custom row content replacing the label text; search still uses `label`. */
     view?: React.ReactNode;
 };

package/dist/Components/SectionRail/SectionRail.d.ts

@@ -1,3 +1,4 @@
 import type { SectionRailProps } from "./SectionRailProps";
+/** Section navigation for a long screen: a vertical rail from `collapseBelow` up, a Select below it; dirty sections are flagged. */
 declare const SectionRail: ({ sections, activeId, onSelect, "aria-label": ariaLabel, dirtyHint, collapseBelow, }: SectionRailProps) => import("react/jsx-runtime").JSX.Element;
 export default SectionRail;

package/dist/Components/SectionRail/SectionRail.js

@@ -29,6 +29,7 @@ const useMinWidth = (minWidth) => {
     }, [query]);
     return matches;
 };
+/** Section navigation for a long screen: a vertical rail from `collapseBelow` up, a Select below it; dirty sections are flagged. */
 const SectionRail = ({ sections, activeId, onSelect, "aria-label": ariaLabel, dirtyHint, collapseBelow = "md", }) => {
     var _a;
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();

package/dist/Components/SectionRail/SectionRailProps.d.ts

@@ -1,7 +1,9 @@
 import type { ReactNode } from "react";
 /** One entry in a SectionRail. */
 export interface RailSection {
+    /** Unique key, matched against `activeId` and passed to `onSelect`. */
     id: string;
+    /** Section name. */
     label: string;
     /** Decorative leading icon, hidden from assistive tech; the label carries the name. */
     icon?: ReactNode;
@@ -10,9 +12,11 @@ export interface RailSection {
 }
 /** Props for the section navigation of a long settings screen: a rail on wide viewports, a Select below `collapseBelow`. */
 export interface SectionRailProps {
+    /** Entries in display order. */
     sections: RailSection[];
     /** Id of the current section; marked `aria-current="true"` (and selected in the Select). */
     activeId: string;
+    /** Called with a section's `id` when it is chosen in the rail or the Select. */
     onSelect: (id: string) => void;
     /** Accessible name of the nav and of the collapsed Select. */
     "aria-label": string;

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

@@ -7,12 +7,15 @@ export type SegmentedControlVariant = "default" | "brandSlide" | "underlineSlide
 export type SegmentedControlOrientation = "horizontal" | "vertical";
 /** One selectable segment; disabled options are skipped by keyboard nav (arrows/Home/End). */
 export type SegmentedControlOption<T extends string = string> = {
+    /** Identity of the option; compared to the top-level `value` to mark it selected and passed to `onChange`. */
     value: T;
+    /** Visible segment text and its accessible name; `shortLabel` may replace it on narrow screens. */
     label: string;
     /** Shown instead of label below the "md" breakpoint, when set; the full label stays the segment's accessible name. */
     shortLabel?: string;
     /** Rendered before the label. */
     icon?: JSX.Element;
+    /** Dims the segment to 50%, blocks clicks and removes it from keyboard navigation. */
     isDisabled?: boolean;
     /** Badge after the label, capped at 99+; omit or pass null/undefined to hide it. */
     count?: number | null;
@@ -35,5 +38,6 @@ export type SegmentedControlProps<T extends string = string> = {
     orientation?: SegmentedControlOrientation;
     /** Background this sits on. Optional: the track is opaque on any backdrop; pass it only to aim the plate's hairline edge at the real backdrop. */
     surface?: string;
+    /** Required accessible name of the radiogroup, e.g. "View mode". */
     "aria-label": string;
 };

package/dist/Components/Select/Select.styles.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Select = void 0;
 const placeholderInk_1 = require("../../Theme/tokens/builders/placeholderInk");
 const controlSizes_1 = require("../../Theme/tokens/primitives/controlSizes");
+const focusRing_styles_1 = require("../../Theme/chakra/focusRing.styles");
 const fieldStyles_1 = require("../Common/fieldStyles");
 const sizeField = (size) => {
     const { h, minH, fontSize, px } = (0, fieldStyles_1.controlSizeStyles)(size);
@@ -31,6 +32,30 @@ exports.Select = {
     sizes: Object.fromEntries(controlSizes_1.CONTROL_SIZE_NAMES.map((size) => [size, sizeField(size)])),
     variants: {
         outline: ({ theme }) => ({ field: (0, fieldStyles_1.fieldControlStyles)(theme.colors) }),
+        filled: ({ theme }) => ({
+            field: {
+                borderRadius: fieldStyles_1.FIELD_RADIUS,
+                _focusVisible: { borderColor: theme.colors.primary[500], ...(0, focusRing_styles_1.fieldFocusVisible)(theme.colors) },
+            },
+        }),
+        flushed: ({ theme }) => {
+            const { colors } = theme;
+            return {
+                field: {
+                    borderColor: colors.boxborder[500],
+                    _hover: { borderColor: (0, fieldStyles_1.fieldHoverBorder)(colors) },
+                    _focusVisible: {
+                        borderColor: colors.primary[500],
+                        borderBottomWidth: "2px",
+                        ...(0, focusRing_styles_1.fieldFocusVisible)(colors),
+                    },
+                    _invalid: { borderColor: colors.semanticText.error, borderBottomWidth: "2px", boxShadow: "none" },
+                },
+            };
+        },
+        unstyled: ({ theme }) => ({
+            field: { borderRadius: fieldStyles_1.FIELD_RADIUS, _focusVisible: (0, focusRing_styles_1.focusVisibleRing)(theme.colors) },
+        }),
     },
     defaultProps: {
         variant: "outline",

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

@@ -60,6 +60,16 @@ declare const SelectNative: React.ForwardRefExoticComponent<{
         isSelected: boolean;
         isActive: boolean;
     }) => React.ReactNode;
+    renderOptionEnd?: (option: OptionProp, state: {
+        isSelected: boolean;
+        isActive: boolean;
+    }) => React.ReactNode;
+    optionAction?: {
+        icon: React.ReactNode;
+        label: string;
+        onAction: (option: OptionProp) => void;
+    };
+    checkPlacement?: "end" | "start";
     renderValue?: (selected: OptionProp[]) => React.ReactNode;
     onCreate?: (label: string) => void;
     createLabel?: (query: string) => React.ReactNode;

package/dist/Components/Select/SelectNative.js

@@ -24,8 +24,13 @@ const optionGroups = (options) => {
     return segments;
 };
 /** Native `<select>` renderer — today's `Select`, unchanged, plus optgroup/disabled from `option.group`/`isDisabled`. */
-const SelectNative = (0, react_1.forwardRef)(function SelectNative({ placeholder = "Select Option", size = controlSizes_1.DEFAULT_CONTROL_SIZE, variant = "outline", icon, onChange, onBlur, onFocus, errorBorderColor, isDisabled, isReadOnly, isRequired = false, value = "", colorScheme, label, id, name, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, error = false, errorMessage, helperText, options = [], width, height, formControlStyle, isInformation = false, informationMessage, selectStyle, noOptionsMessage, }, ref) {
+const SelectNative = (0, react_1.forwardRef)(function SelectNative({ placeholder = "Select Option", size = controlSizes_1.DEFAULT_CONTROL_SIZE, variant = "outline", icon, onChange, onBlur, onFocus, errorBorderColor, isDisabled, isReadOnly, isRequired = false, value, defaultValue, colorScheme, label, id, name, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, error = false, errorMessage, helperText, options = [], width, height, formControlStyle, isInformation = false, informationMessage, selectStyle, noOptionsMessage, }, ref) {
     const ids = (0, useFieldIds_1.useFieldIds)(id, { error, errorMessage, helperText });
+    const [internalValue, setInternalValue] = (0, react_1.useState)(defaultValue !== null && defaultValue !== void 0 ? defaultValue : "");
+    const wasControlledRef = (0, react_1.useRef)(false);
+    if (value !== undefined)
+        wasControlledRef.current = true;
+    const shownValue = value !== null && value !== void 0 ? value : (wasControlledRef.current ? "" : internalValue);
     const getOptionsList = (0, react_1.useCallback)(() => {
         if (!options.length) {
             return (0, jsx_runtime_1.jsx)("option", { value: "", children: String(noOptionsMessage !== null && noOptionsMessage !== void 0 ? noOptionsMessage : "No Options") });
@@ -41,9 +46,11 @@ const SelectNative = (0, react_1.forwardRef)(function SelectNative({ placeholder
         if (isReadOnly)
             return;
         const selectedOption = options.find((option) => option.id.toString() === event.target.value.toString());
-        if (selectedOption)
-            onChange(selectedOption);
+        if (!selectedOption)
+            return;
+        setInternalValue(selectedOption.id);
+        onChange(selectedOption);
     };
-    return ((0, jsx_runtime_1.jsxs)(react_2.FormControl, { isInvalid: error, 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.jsx)(react_2.Select, { ref: ref, ...ids.controlProps, name: name, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, placeholder: placeholder, size: size, variant: variant, icon: icon, iconSize: `${controlSizes_1.CONTROL_SIZES[size].iconSize}px`, isInvalid: error, isRequired: isRequired, value: value, onChange: handleOnChange, onBlur: onBlur, onFocus: onFocus, isDisabled: isDisabled, isReadOnly: isReadOnly, colorScheme: colorScheme, errorBorderColor: errorBorderColor, style: selectStyle, ...(height != null && height !== "" ? { minH: height, h: height } : {}), children: getOptionsList() }), (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.jsxs)(react_2.FormControl, { isInvalid: error, 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.jsx)(react_2.Select, { ref: ref, ...ids.controlProps, name: name, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, placeholder: placeholder, size: size, variant: variant, icon: icon, iconSize: `${controlSizes_1.CONTROL_SIZES[size].iconSize}px`, isInvalid: error, isRequired: isRequired, value: shownValue, onChange: handleOnChange, onBlur: onBlur, onFocus: onFocus, isDisabled: isDisabled, isReadOnly: isReadOnly, colorScheme: colorScheme, errorBorderColor: errorBorderColor, style: selectStyle, ...(height != null && height !== "" ? { minH: height, h: height } : {}), children: getOptionsList() }), (0, jsx_runtime_1.jsx)(FieldMessage_1.default, { error: error, errorMessage: errorMessage, helperText: helperText, helperId: ids.helperId, errorId: ids.errorId })] }));
 });
 exports.default = SelectNative;