@akad/design-system 1.1.1 → 1.1.2

package/react/src/components/molecules/EditableSelect/EditableSelect.config.d.ts

@@ -77,6 +77,10 @@ export interface EditableSelectOnSelectHandlerProps {
     type: FunctionConstructor;
     default: () => void;
 }
+export interface EditableSelectOnClearHandlerProps {
+    type: FunctionConstructor;
+    default: () => void;
+}
 export interface EditableSelectConfig {
     name: string;
     class: string;
@@ -97,6 +101,7 @@ export interface EditableSelectConfig {
         onBlurHandler: EditableSelectOnBlurHandlerProps;
         onFocusHandler: EditableSelectOnFocusHandlerProps;
         onSelectHandler: EditableSelectOnSelectHandlerProps;
+        onClearHandler: EditableSelectOnClearHandlerProps;
         placeholder: EditableSelectPlaceholderProps;
     };
 }

package/react/src/components/molecules/EditableSelect/EditableSelect.d.ts

@@ -1,7 +1,9 @@
 import { EditableSelectOption } from './EditableSelect.config';
 
 /**
- * DsEditableSelect - A select component with two usage modes:
+ * DsEditableSelect - A combobox-style select component with two usage modes.
+ *
+ * ## Modes
  *
  * **Mode 1: Autocomplete (default)**
  * The user types in the input and the parent component is responsible for
@@ -31,8 +33,66 @@ import { EditableSelectOption } from './EditableSelect.config';
  *   showOptionsOnFocus
  *   onChangeHandler={handleChange}
  *   onSelectHandler={handleSelect}
+ *   onClearHandler={handleClear}
+ * />
+ * ```
+ *
+ * ## Selection lifecycle
+ *
+ * - `onChangeHandler(event)` — fires on every keystroke (both modes). Update
+ *   the displayed text state from `event.target.value`.
+ * - `onSelectHandler(option)` — fires when a selection is committed:
+ *   1. user clicks an option in the dropdown (both modes), OR
+ *   2. (Searchable Dropdown only) user blurs the input with text that matches
+ *      an option's label exactly (case-insensitive, trimmed — auto-select on
+ *      blur).
+ *   Update both the displayed text (to `option.label`) and the form-validated
+ *   value (to `option.value`).
+ * - `onClearHandler()` — **Searchable Dropdown only**. Fires when the
+ *   selection becomes invalid:
+ *   1. user blurs with text that does not match any option, OR
+ *   2. while typing, the value transitions from matching an option to not
+ *      matching (e.g., user appends a character to a previously matched label).
+ *   Clear the form-validated value so subsequent validation sees no selection.
+ *
+ * In Searchable Dropdown mode, on blur with no match the component **also**
+ * dispatches a native `input` event with empty value to force the input
+ * display to clear via your existing `onChangeHandler`. This guarantees the
+ * display does not retain a stale unmatched value, even if `onClearHandler`
+ * is not wired to clear the display.
+ *
+ * Autocomplete mode keeps the legacy contract: blur only fires
+ * `onBlurHandler`; typing only fires `onChangeHandler`. No auto-select, no
+ * clear, no native dispatch.
+ *
+ * ## Highlighted option
+ *
+ * The option whose label equals `value` (case-sensitive, exact) is rendered
+ * with the `--selected` modifier class for visual feedback when the dropdown
+ * reopens after a selection.
+ *
+ * ## Recommended consumer state shape
+ *
+ * Keep two separate state fields — one for what shows in the input, one for
+ * what the form validates:
+ *
+ * ```tsx
+ * const [displayValue, setDisplayValue] = useState('');
+ * const [selectedValue, setSelectedValue] = useState<string | null>(null);
+ *
+ * <DsEditableSelect
+ *   value={displayValue}
+ *   onChangeHandler={(e) => setDisplayValue(e.target.value)}
+ *   onSelectHandler={(opt) => {
+ *     setDisplayValue(opt.label);
+ *     setSelectedValue(opt.value);
+ *   }}
+ *   onClearHandler={() => setSelectedValue(null)}
  * />
  * ```
+ *
+ * Validate `selectedValue`, not `displayValue`. This guarantees that typed-but-
+ * not-selected text is treated as no selection.
  */
 export interface DsEditableSelectProps {
     label?: string;
@@ -43,6 +103,7 @@ export interface DsEditableSelectProps {
     options?: EditableSelectOption[];
     onChangeHandler?: (event: React.ChangeEvent<HTMLInputElement> | React.FormEvent<HTMLInputElement>) => void;
     onSelectHandler?: (selectedOption: object) => void;
+    onClearHandler?: () => void;
     icon?: string;
     noOptionsMessage?: string;
     disabled?: boolean;
@@ -66,7 +127,7 @@ export interface DsEditableSelectProps {
     inputOnKeyDownHandler?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
 }
 declare const DsEditableSelect: {
-    ({ label, name, testId, value, options, size, onChangeHandler, onSelectHandler, icon, noOptionsMessage, disabled, status, onBlurHandler, onFocusHandler, animated, placeholder, loading, showOptionsOnFocus, inputType, inputMin, inputMax, inputTooltip, inputTooltipPosition, inputTooltipPlacement, inputFeedback, inputHasFeedback, inputNoMargin, inputMask, inputOnKeyDownHandler, }: DsEditableSelectProps): import("react/jsx-runtime").JSX.Element;
+    ({ label, name, testId, value, options, size, onChangeHandler, onSelectHandler, onClearHandler, icon, noOptionsMessage, disabled, status, onBlurHandler, onFocusHandler, animated, placeholder, loading, showOptionsOnFocus, inputType, inputMin, inputMax, inputTooltip, inputTooltipPosition, inputTooltipPlacement, inputFeedback, inputHasFeedback, inputNoMargin, inputMask, inputOnKeyDownHandler, }: DsEditableSelectProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
 export default DsEditableSelect;

package/scss/core/components/molecules/editable-select.scss

@@ -105,6 +105,10 @@
     text-align: left;
     width: 100%;
 
+    &--selected {
+      background-color: var(--color__neutral--30);
+    }
+
     &:hover {
       background-color: var(--color__info);
       color: var(--color__neutral--00);