@codecademy/gamut 72.2.3-alpha.c298d6.0 → 72.2.3-alpha.f0a032.0

package/agent-tools/skills/gamut-forms/SKILL.md

@@ -26,6 +26,22 @@ For typical product forms, prefer `GridForm` (declarative `fields`, `LayoutGrid`
 
 ---
 
+## SelectDropdown vs Select
+
+Use `Select` for standard single-select fields where bundle size matters and no special styling is needed. Use `SelectDropdown` when the design calls for any of:
+
+- Styled dropdown menu (react-select appearance)
+- Search / typeahead
+- Multi-select with tags
+- Creatable options
+- Option icons, subtitles, right labels, abbreviations, or grouped options
+
+`SelectDropdown` carries a larger JS dependency (react-select); don't reach for it as a default drop-in for `Select`.
+
+For full SelectDropdown API detail — controlled vs uncontrolled patterns, creatable options, react-select action metadata — use [`gamut-select-dropdown`](../gamut-select-dropdown/SKILL.md). Generic `FormGroup` wiring (labels, errors, live regions) still applies as documented below.
+
+---
+
 ## `FormGroup` (baseline)
 
 `packages/gamut/src/Form/elements/FormGroup.tsx`

package/agent-tools/skills/gamut-select-dropdown/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: gamut-select-dropdown
+description: Use when implementing or auditing SelectDropdown — single/multi modes, controlled vs uncontrolled value, creatable options, FormGroup wiring, and onChange contract. Pair with gamut-forms for error live regions, ConnectedForm, and field-level validation.
+---
+
+# Gamut SelectDropdown
+
+Styled dropdown built on react-select.
+
+Source: `@codecademy/gamut` — [SelectDropdown.tsx](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Form/SelectDropdown/SelectDropdown.tsx)
+
+See also: [`gamut-forms`](../gamut-forms/SKILL.md) — FormGroup wiring, error regions, and validation UX.
+
+Storybook: [Atoms / FormInputs / SelectDropdown](https://gamut.codecademy.com/?path=/docs-atoms-forminputs-selectdropdown--docs)
+
+---
+
+## When to use SelectDropdown vs Select
+
+Use `Select` for standard single-select forms with minimal bundle cost. Use `SelectDropdown` when designs specify the styled dropdown menu, search, multi-select tags, creatable options, icons, groups, or abbreviations. SelectDropdown has a larger JavaScript dependency (react-select).
+
+---
+
+## Options
+
+`options` accepts plain strings or option objects. `value` is always a string and references an option's `value`.
+
+| Field          | Required | Notes                                                                |
+| -------------- | -------- | -------------------------------------------------------------------- |
+| `label`        | yes      | Display text                                                         |
+| `value`        | yes      | Unique string; what `value` / `string[]` reference                   |
+| `disabled`     | no       | Option cannot be selected                                            |
+| `subtitle`     | no       | Secondary text below the label                                       |
+| `rightLabel`   | no       | Text on the right side of the option                                 |
+| `icon`         | no       | A `@codecademy/gamut-icons` component                                |
+| `abbreviation` | no       | Short text shown in the input while the full label shows in the menu |
+
+Grouped options: `{ label, options: [...], divider? }` (extends react-select `GroupBase`; `divider` draws a rule above the group).
+
+---
+
+## Controlled vs uncontrolled
+
+SelectDropdown does **not** accept `defaultValue`.
+
+| Mode             | Uncontrolled                                       | Controlled                                                                        |
+| ---------------- | -------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Single           | Not supported                                      | `value` (string) + update in `onChange`                                           |
+| Multi            | Omit `value` or pass non-array (`undefined`, `''`) | `value: string[]` + update in `onChange`                                          |
+| Creatable single | Not supported                                      | Same as single; `onCreateOption` appends to `options`                             |
+| Creatable multi  | Omit `value`; `onCreateOption` for options         | `value: string[]`; update in `onChange` on every change including `create-option` |
+
+Single-select selection is derived from the `value` prop only — internal state is not kept. Multi-select without `value: string[]` keeps selection in internal `multiValues`.
+
+**Controlled creatable multi pitfall:** Updating `options` alone without syncing `value` in `onChange` clears selection when options re-render.
+
+### When to use uncontrolled (multi only)
+
+Uncontrolled multi is appropriate when:
+
+- No other part of the UI needs to react to the current selection (no live summary, no dependent field, no enabled/disabled button).
+- You only need the value at form submission — via `FormData`, a submit handler reading the DOM, or react-hook-form's `getValues`.
+- Simplicity is the priority; omitting `value` means one less piece of state to manage.
+
+```tsx
+// Good fit: a "tags" field where only the submitted array matters
+<SelectDropdown
+  multiple
+  name="tags"
+  options={tagOptions}
+  onCreateOption={(v) => setTagOptions((prev) => [...prev, v])}
+/>
+```
+
+### When to use controlled
+
+Use controlled when:
+
+- Another part of the UI must reflect the current selection in real time (summary text, a filtered list, an enable/disable condition).
+- You need to pre-populate from an API response, reset on cancel, or sync with a form library like react-hook-form.
+- You are using single-select (the only supported mode for single).
+
+```tsx
+// Good fit: pre-populate from API, clear on cancel, show live summary
+const [selected, setSelected] = useState<string[]>(initialValues);
+
+<SelectDropdown
+  multiple
+  name="languages"
+  options={languageOptions}
+  value={selected}
+  onChange={(opts) => setSelected(opts.map((o) => o.value))}
+/>
+<p>Selected: {selected.join(', ') || 'none'}</p>
+```
+
+---
+
+## onChange contract
+
+`onChange` receives option object(s), not `event.target.value`:
+
+```tsx
+// Single
+onChange={(option) => setValue(option.value)}
+
+// Multi
+onChange={(selected) => setValue(selected.map((o) => o.value))}
+```
+
+Second argument is react-select `ActionMeta`. For creatable creates: `meta.action === 'create-option'`. Do **not** pass `onCreateOption` to react-select directly — Gamut invokes it from `changeHandler` while still forwarding `create-option` to consumer `onChange`.
+
+---
+
+## Creatable
+
+- `isCreatable` forces `isSearchable: true` (TypeScript enforces this).
+- `onCreateOption(inputValue)` — convenience hook to append to `options`.
+- `onChange(selected, meta)` — use `meta.action === 'create-option'` to sync controlled `value` and `options` together.
+- `isValidNewOption` — return `false` to hide the Add row.
+- `validationMessage` — replaces menu "No options" text; mirror in `FormGroup` `error` for field-level feedback.
+
+**Validation after blur:** react-select clears input on blur before `onBlur` fires, so the value is gone by the time you'd validate it. Store the last typed value in a ref and re-validate from it on `input-blur`:
+
+```tsx
+const lastInput = useRef('');
+
+<SelectDropdown
+  isCreatable
+  onInputChange={(value, { action }) => {
+    if (action === 'input-change') lastInput.current = value;
+    if (action === 'input-blur') validate(lastInput.current);
+  }}
+/>;
+```
+
+---
+
+## FormGroup wiring
+
+- `FormGroup` `htmlFor` must match control `id` (not `name`). Alternatively, pass `htmlFor` directly on SelectDropdown and it becomes `id` downstream.
+- Pass `name` on SelectDropdown (required for forms).
+- Pass `aria-label` (required for forms); it must match the FormGroupLabel `htmlFor`.
+- Pass `error` boolean when FormGroup has an error.
+- Generic FormGroup live-region behavior: see [`gamut-forms`](../gamut-forms/SKILL.md).
+
+```tsx
+<FormGroup htmlFor="country" isSoloField label="Country" error={errors.country}>
+  <SelectDropdown
+    id="country"
+    name="country"
+    aria-label="country"
+    options={options}
+    value={value}
+    error={Boolean(errors.country)}
+    onChange={(option) => setValue(option.value)}
+  />
+</FormGroup>
+```
+
+---
+
+## Styling & layout props
+
+| Prop                | Type                     | Default  | Notes                                                     |
+| ------------------- | ------------------------ | -------- | --------------------------------------------------------- |
+| `size`              | `'small' \| 'medium'`    | `medium` | Control height/density                                    |
+| `shownOptionsLimit` | `1`–`6`                  | `6`      | Visible options before the menu scrolls                   |
+| `inputWidth`        | `string \| number`       | —        | Width of the input independent of the menu                |
+| `dropdownWidth`     | `string \| number`       | —        | Width of the menu independent of the input                |
+| `menuAlignment`     | `'left' \| 'right'`      | `left`   | Menu edge alignment                                       |
+| `zIndex`            | `number`                 | auto     | Menu z-index                                              |
+| `inputProps`        | `{ hidden?, combobox? }` | —        | `data-*` / `aria-*` only, forwarded to the input elements |
+
+---
+
+## Examples
+
+### Single (controlled)
+
+```tsx
+const [value, setValue] = useState('us');
+
+<SelectDropdown
+  name="country"
+  options={options}
+  value={value}
+  onChange={(option) => setValue(option.value)}
+/>;
+```
+
+### Multi (uncontrolled)
+
+```tsx
+<SelectDropdown
+  multiple
+  name="tags"
+  options={options}
+  onChange={(selected) => console.log(selected)}
+/>
+```
+
+### Creatable multi (uncontrolled)
+
+```tsx
+const [options, setOptions] = useState(['Apple', 'Banana']);
+
+<SelectDropdown
+  isCreatable
+  multiple
+  name="fruits"
+  options={options}
+  onCreateOption={(v) => setOptions((prev) => [...prev, v])}
+/>;
+```
+
+### Creatable multi (controlled)
+
+```tsx
+const [options, setOptions] = useState(['Apple', 'Banana']);
+const [value, setValue] = useState<string[]>([]);
+
+<SelectDropdown
+  isCreatable
+  multiple
+  name="fruits"
+  options={options}
+  value={value}
+  onChange={(selected, meta) => {
+    setValue(selected.map((o) => o.value));
+    if (meta.action === 'create-option' && meta.option) {
+      setOptions((prev) => [...prev, meta.option.value]);
+    }
+  }}
+/>;
+```

package/dist/Button/IconButton.js

@@ -16,7 +16,6 @@ export const IconButton = /*#__PURE__*/forwardRef(({
   const iconSize = iconSizeMapping[buttonSize];
   return /*#__PURE__*/_jsx(ToolTip, {
     info: tip,
-    closeOnClick: true,
     ...tipProps,
     children: /*#__PURE__*/_jsx(IconButtonBase, {
       ...props,

package/dist/Form/SelectDropdown/SelectDropdown.js

@@ -1,28 +1,14 @@
 import { useTheme } from '@emotion/react';
-import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { useId, useMemo, useRef, useState } from 'react';
 import * as React from 'react';
-import { parseOptions } from '../utils';
-import { AbbreviatedSingleValue, CustomContainer, CustomInput, CustomValueContainer, DropdownButton, formatGroupLabel, formatOptionLabel, IconOption, MultiValueRemoveButton, MultiValueWithColorMode, onFocus, RemoveAllButton, SelectDropdownContext, TypedReactSelect } from './elements';
-import { getMemoizedStyles } from './styles';
-import { filterValueFromOptions, isMultipleSelectProps, isOptionsGrouped, isSingleSelectProps, removeValueFromSelectedOptions } from './utils';
+import { onFocus } from './core/accessibility';
+import { defaultComponents } from './core/constants';
+import { getMemoizedStyles } from './core/styles';
+import { resolveNoOptionsMessage } from './core/utils';
+import { formatGroupLabel, formatOptionLabel, SelectDropdownContext, TypedReactSelect } from './elements';
+import { useSelectHandlers } from './hooks/useSelectHandlers';
+import { useSelectOptions } from './hooks/useSelectOptions';
 import { jsx as _jsx } from "react/jsx-runtime";
-const defaultProps = {
-  name: undefined,
-  components: {
-    DropdownIndicator: DropdownButton,
-    IndicatorSeparator: () => null,
-    ClearIndicator: RemoveAllButton,
-    SelectContainer: CustomContainer,
-    ValueContainer: CustomValueContainer,
-    MultiValue: MultiValueWithColorMode,
-    MultiValueRemove: MultiValueRemoveButton,
-    Option: IconOption,
-    SingleValue: AbbreviatedSingleValue,
-    Input: CustomInput
-  }
-};
-const onChangeAction = 'select-option';
-
 /**
  * A flexible dropdown select component built on top of react-select.
  *
@@ -73,101 +59,58 @@ export const SelectDropdown = ({
   disabled,
   dropdownWidth,
   error,
+  formatCreateLabel = inputValue => `Add "${inputValue}"`,
   id,
   inputProps,
   inputWidth,
-  isSearchable = false,
+  isCreatable = false,
+  isSearchable: isSearchableProp = false,
+  isValidNewOption,
   menuAlignment = 'left',
   multiple,
   name,
   onChange,
+  onCreateOption,
+  onInputChange,
   options,
   placeholder = 'Select an option',
   shownOptionsLimit = 6,
   size,
+  validationMessage,
   value,
   zIndex,
   ...rest
 }) => {
+  // isSearchable is forced true when isCreatable is true (CreatableSelect requires a text input)
+  const isSearchable = isCreatable || isSearchableProp;
   const rawInputId = useId();
   const inputId = name ?? `${id}-select-dropdown-${rawInputId}`;
-  const [activated, setActivated] = useState(false);
-  const [currentFocusedValue, setCurrentFocusedValue] = useState(undefined);
-
-  // these are used to programatically manage the focus state of our multi-select options + 'Remove all' button
   const removeAllButtonRef = useRef(null);
   const selectInputRef = useRef(null);
-  const selectOptions = useMemo(() => {
-    if (!options || Array.isArray(options) && !options.length || typeof options === 'object' && !Array.isArray(options) && Object.keys(options).length === 0) {
-      return [];
-    }
-    if (isOptionsGrouped(options)) {
-      return options;
-    }
-    return parseOptions({
-      options,
-      id,
-      size
-    });
-  }, [options, id, size]);
-  const parsedValue = useMemo(() => {
-    if (isOptionsGrouped(selectOptions)) {
-      for (const group of selectOptions) {
-        if (group.options) {
-          const foundOption = group.options.find(option => option.value === value);
-          if (foundOption) return foundOption;
-        }
-      }
-      return undefined;
-    }
-    return selectOptions.find(option => option.value === value);
-  }, [selectOptions, value]);
-  const [multiValues, setMultiValues] = useState(multiple &&
-  // To keep this efficient for non-multiSelect
-  filterValueFromOptions(selectOptions, value, isOptionsGrouped(selectOptions)));
-
-  // If the caller changes the initial value, let's update our value to match.
-  useEffect(() => {
-    const newMultiValues = filterValueFromOptions(selectOptions, value, isOptionsGrouped(selectOptions));
-    if (newMultiValues !== multiValues) setMultiValues(newMultiValues);
-
-    //
-    // We only update this when our passed in options or value changes, not multiValues.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [options, value]);
-  const changeHandler = useCallback(optionEvent => {
-    setActivated(true);
-
-    // We have to do this because the version of typescript we have doesn't have the transitivity of these type guards yet. But, we will soon!
-    // Should probably come with: https://codecademy.atlassian.net/browse/GM-354
-    const onChangeProps = {
-      onChange,
-      multiple
-    };
-    if (isSingleSelectProps(onChangeProps)) {
-      const singleOptionEvent = optionEvent;
-      onChangeProps.onChange?.(singleOptionEvent, {
-        action: onChangeAction,
-        option: singleOptionEvent
-      });
-    }
-    if (isMultipleSelectProps(onChangeProps)) {
-      setMultiValues(optionEvent);
-      onChangeProps.onChange?.(optionEvent, {
-        action: onChangeAction,
-        option: undefined // At the moment this isn't used, but when multi select is built for real, boom (https://codecademy.atlassian.net/browse/GM-354)
-      });
-    }
-  }, [onChange, multiple]);
-  const keyPressHandler = e => {
-    if (multiple && e.key === 'Enter' && currentFocusedValue && multiValues) {
-      const newMultiValues = removeValueFromSelectedOptions(multiValues, currentFocusedValue);
-      if (newMultiValues !== multiValues) setMultiValues(newMultiValues);
-    }
-    if (removeAllButtonRef.current !== null && e.key === 'ArrowRight' && multiValues && currentFocusedValue === multiValues[multiValues.length - 1].value) {
-      removeAllButtonRef.current.focus();
-    }
-  };
+  const [currentFocusedValue, setCurrentFocusedValue] = useState(undefined);
+  const {
+    selectOptions,
+    parsedValue
+  } = useSelectOptions({
+    options,
+    id,
+    size,
+    value: value
+  });
+  const {
+    activated,
+    multiValues,
+    changeHandler,
+    keyPressHandler
+  } = useSelectHandlers({
+    onChange,
+    multiple,
+    onCreateOption,
+    selectOptions,
+    value,
+    currentFocusedValue,
+    removeAllButtonRef
+  });
   const theme = useTheme();
   const memoizedStyles = useMemo(() => {
     return getMemoizedStyles(theme, zIndex);
@@ -180,14 +123,15 @@ export const SelectDropdown = ({
       selectInputRef
     },
     children: /*#__PURE__*/_jsx(TypedReactSelect, {
-      ...defaultProps,
       activated: activated,
       "aria-live": "assertive",
       ariaLiveMessages: {
         onFocus
       },
+      components: defaultComponents,
       dropdownWidth: dropdownWidth,
       error: Boolean(error),
+      formatCreateLabel: formatCreateLabel,
       formatGroupLabel: formatGroupLabel,
       formatOptionLabel: formatOptionLabel,
       id: id || rest.htmlFor || rawInputId,
@@ -196,12 +140,15 @@ export const SelectDropdown = ({
         ...inputProps
       },
       inputWidth: inputWidth,
+      isCreatable: isCreatable,
       isDisabled: disabled,
       isMulti: multiple,
       isOptionDisabled: option => option.disabled,
       isSearchable: isSearchable,
+      isValidNewOption: isValidNewOption,
       menuAlignment: menuAlignment,
       name: name,
+      noOptionsMessage: resolveNoOptionsMessage(validationMessage),
       options: selectOptions,
       placeholder: placeholder,
       selectRef: selectInputRef,
@@ -210,7 +157,8 @@ export const SelectDropdown = ({
       styles: memoizedStyles,
       value: multiple ? multiValues : parsedValue,
       onChange: changeHandler,
-      onKeyDown: multiple ? e => keyPressHandler(e) : undefined,
+      onInputChange: onInputChange,
+      onKeyDown: multiple ? keyPressHandler : undefined,
       ...rest
     })
   });

package/dist/Form/SelectDropdown/core/accessibility.d.ts

@@ -0,0 +1,3 @@
+import { AriaOnFocus } from 'react-select';
+import { ExtendedOption } from '../types';
+export declare const onFocus: AriaOnFocus<ExtendedOption>;

package/dist/Form/SelectDropdown/core/accessibility.js

@@ -0,0 +1,12 @@
+export const onFocus = ({
+  focused: {
+    label,
+    subtitle,
+    rightLabel,
+    disabled
+  }
+}) => {
+  const formattedSubtitle = `, ${subtitle}`;
+  const formattedRightLabel = `, ${rightLabel}`;
+  return `You are currently focused on option ${label}${subtitle ? formattedSubtitle : ''} ${rightLabel ? formattedRightLabel : ''}${disabled ? ', disabled' : ''}`;
+};

package/dist/Form/SelectDropdown/core/constants.d.ts

@@ -0,0 +1,13 @@
+export declare const defaultComponents: {
+    DropdownIndicator: (props: import("../types").SizedIndicatorProps) => import("react/jsx-runtime").JSX.Element;
+    IndicatorSeparator: () => null;
+    ClearIndicator: (props: import("../types").SizedIndicatorProps) => import("react/jsx-runtime").JSX.Element;
+    SelectContainer: ({ children, ...rest }: import("../types").CustomSelectComponentProps<(<Option_18, IsMulti_18 extends boolean, Group_18 extends import("react-select").GroupBase<Option_18>>(props: import("react-select").ContainerProps<Option_18, IsMulti_18, Group_18>) => import("@emotion/react").jsx.JSX.Element)>) => import("react/jsx-runtime").JSX.Element;
+    ValueContainer: ({ ...rest }: import("../types").CustomSelectComponentProps<(<Option_20, IsMulti_20 extends boolean, Group_20 extends import("react-select").GroupBase<Option_20>>(props: import("react-select").ValueContainerProps<Option_20, IsMulti_20, Group_20>) => import("@emotion/react").jsx.JSX.Element)>) => import("react/jsx-runtime").JSX.Element;
+    MultiValue: (props: import("react-select").MultiValueProps<import("..").ExtendedOption, true, import("react-select").GroupBase<import("..").ExtendedOption>>) => import("react/jsx-runtime").JSX.Element;
+    MultiValueRemove: (props: import("react-select").MultiValueRemoveProps<import("..").ExtendedOption, true, import("react-select").GroupBase<import("..").ExtendedOption>>) => import("react/jsx-runtime").JSX.Element;
+    Option: ({ children, ...rest }: import("../types").CustomSelectComponentProps<(<Option_16, IsMulti_16 extends boolean, Group_16 extends import("react-select").GroupBase<Option_16>>(props: import("react-select").OptionProps<Option_16, IsMulti_16, Group_16>) => import("@emotion/react").jsx.JSX.Element)>) => import("react/jsx-runtime").JSX.Element;
+    SingleValue: (props: import("react-select").SingleValueProps<import("..").ExtendedOption, false>) => import("react/jsx-runtime").JSX.Element;
+    Input: ({ ...rest }: import("../types").CustomSelectComponentProps<(<Option_7, IsMulti_7 extends boolean, Group_7 extends import("react-select").GroupBase<Option_7>>(props: import("react-select").InputProps<Option_7, IsMulti_7, Group_7>) => import("@emotion/react").jsx.JSX.Element)>) => import("react/jsx-runtime").JSX.Element;
+};
+export declare const ON_CHANGE_ACTION: "select-option";

package/dist/Form/SelectDropdown/core/constants.js

@@ -0,0 +1,14 @@
+import { AbbreviatedSingleValue, CustomContainer, CustomInput, CustomValueContainer, DropdownButton, IconOption, MultiValueRemoveButton, MultiValueWithColorMode, RemoveAllButton } from '../elements';
+export const defaultComponents = {
+  DropdownIndicator: DropdownButton,
+  IndicatorSeparator: () => null,
+  ClearIndicator: RemoveAllButton,
+  SelectContainer: CustomContainer,
+  ValueContainer: CustomValueContainer,
+  MultiValue: MultiValueWithColorMode,
+  MultiValueRemove: MultiValueRemoveButton,
+  Option: IconOption,
+  SingleValue: AbbreviatedSingleValue,
+  Input: CustomInput
+};
+export const ON_CHANGE_ACTION = 'select-option';

package/dist/Form/SelectDropdown/{styles.js → core/styles.js}

@@ -1,6 +1,6 @@
 import { css, states, variant } from '@codecademy/gamut-styles';
-import { dismissSharedStyles, tagBaseStyles, tagLabelFontSize, tagLabelPadding } from '../../Tag/styles';
-import { formBaseComponentStyles, formBaseFieldStylesObject, formFieldDisabledStyles, formFieldPaddingStyles, InputSelectors } from '../styles';
+import { dismissSharedStyles, tagBaseStyles, tagLabelFontSize, tagLabelPadding } from '../../../Tag/styles';
+import { formBaseComponentStyles, formBaseFieldStylesObject, formFieldDisabledStyles, formFieldPaddingStyles, InputSelectors } from '../../styles';
 const selectDropdownStyles = css({
   ...formBaseFieldStylesObject,
   display: 'flex',
@@ -62,7 +62,7 @@ const textColor = css({
   color: 'text'
 });
 const placeholderColor = css({
-  color: 'text-disabled'
+  color: 'text-secondary'
 });
 export const getMemoizedStyles = (theme, zIndex) => {
   return {
@@ -137,6 +137,8 @@ export const getMemoizedStyles = (theme, zIndex) => {
           error: state.selectProps.error,
           theme
         }),
+        // Drop react-select's default menu drop shadow; the border above defines the edge.
+        boxShadow: 'none',
         ...(dropdownWidth ? {
           minWidth: dropdownWidth,
           width: dropdownWidth
@@ -194,16 +196,32 @@ export const getMemoizedStyles = (theme, zIndex) => {
         backgroundColor: theme.colors['secondary-hover']
       }
     }),
-    option: (provided, state) => ({
-      ...getOptionBackground(state.isSelected, state.isFocused)({
-        theme
-      }),
-      alignItems: 'center',
-      color: state.isDisabled ? 'text-disabled' : 'default',
-      cursor: state.isDisabled ? 'not-allowed' : 'pointer',
-      display: 'flex',
-      padding: state.selectProps.size === 'small' ? '3px 14px' : '11px 14px'
+    noOptionsMessage: provided => ({
+      ...provided,
+      color: theme.colors['text-secondary']
     }),
+    option: (provided, state) => {
+      const isNew = state.data?.__isNew__;
+      const isSmall = state.selectProps.size === 'small';
+      return {
+        ...getOptionBackground(state.isSelected, state.isFocused)({
+          theme
+        }),
+        alignItems: 'center',
+        color: state.isDisabled ? theme.colors['text-disabled'] : isNew ? theme.colors.primary : theme.colors.text,
+        cursor: state.isDisabled ? 'not-allowed' : 'pointer',
+        display: 'flex',
+        padding: isSmall ? '3px 14px' : '11px 14px',
+        ...(isNew && {
+          // Gradient creates the 1px divider line at the top edge of the option background
+          backgroundImage: `linear-gradient(${theme.colors['text-disabled']} 1px, transparent 1px)`,
+          backgroundPosition: '0 0',
+          backgroundRepeat: 'no-repeat',
+          backgroundSize: '100% 1px',
+          paddingTop: isSmall ? '11px' : '19px'
+        })
+      };
+    },
     placeholder: provided => ({
       ...provided,
       ...placeholderColor({

package/dist/Form/SelectDropdown/{utils.d.ts → core/utils.d.ts}

@@ -1,7 +1,14 @@
-import { SelectOptionBase } from '../utils';
-import { BaseOnChangeProps, ExtendedOption, MultiSelectDropdownProps, SelectDropdownGroup, SelectDropdownOptions, SelectDropdownProps, SingleSelectDropdownProps } from './types';
+import * as React from 'react';
+import { ActionMeta, Options as OptionsType } from 'react-select';
+import { SelectOptionBase } from '../../utils';
+import { BaseOnChangeProps, ExtendedOption, MultiSelectDropdownProps, OptionStrict, SelectDropdownGroup, SelectDropdownOptions, SelectDropdownProps, SingleSelectDropdownProps } from '../types';
 export declare const isMultipleSelectProps: (props: BaseOnChangeProps) => props is MultiSelectDropdownProps;
 export declare const isSingleSelectProps: (props: BaseOnChangeProps) => props is SingleSelectDropdownProps;
+/**
+ * Resolves the value for a newly created option from react-select action metadata
+ * or the onChange option payload. Returns undefined when no reliable value exists.
+ */
+export declare const getCreatedOptionValue: (optionEvent: OptionStrict | OptionsType<OptionStrict>, actionMeta: ActionMeta<OptionStrict>, multiple?: boolean) => string | undefined;
 export declare const isOptionGroup: (obj: unknown) => obj is SelectDropdownGroup;
 export declare const isOptionsGrouped: (options: SelectDropdownOptions) => options is SelectDropdownGroup[];
 /**
@@ -23,4 +30,7 @@ export declare const filterValueFromOptions: (options: SelectOptionBase[] | Sele
  * @param value - The value or values to remove
  * @returns New array with the specified values removed
  */
+export declare const resolveNoOptionsMessage: (validationMessage: SelectDropdownProps["validationMessage"]) => ((obj: {
+    inputValue: string;
+}) => React.ReactNode) | undefined;
 export declare const removeValueFromSelectedOptions: (selectedOptions: ExtendedOption[] | SelectOptionBase[], value: SelectDropdownProps["value"]) => SelectOptionBase[];

package/dist/Form/SelectDropdown/{utils.js → core/utils.js}

@@ -1,5 +1,21 @@
 export const isMultipleSelectProps = props => !!props.multiple;
 export const isSingleSelectProps = props => !props.multiple;
+/**
+ * Resolves the value for a newly created option from react-select action metadata
+ * or the onChange option payload. Returns undefined when no reliable value exists.
+ */
+export const getCreatedOptionValue = (optionEvent, actionMeta, multiple) => {
+  const metaValue = actionMeta.option?.value;
+  if (metaValue) return metaValue;
+  if (!multiple) {
+    const {
+      value
+    } = optionEvent;
+    return value || undefined;
+  }
+  const newOption = optionEvent.find(option => option.__isNew__);
+  return newOption?.value || undefined;
+};
 export const isOptionGroup = obj => obj != null && typeof obj === 'object' && 'options' in obj && obj.options !== undefined;
 export const isOptionsGrouped = options => Array.isArray(options) && options.some(option => isOptionGroup(option));
 
@@ -28,6 +44,13 @@ export const filterValueFromOptions = (options, value, optionsAreGrouped) => {
  * @param value - The value or values to remove
  * @returns New array with the specified values removed
  */
+export const resolveNoOptionsMessage = validationMessage => {
+  if (validationMessage === undefined) return undefined;
+  if (typeof validationMessage === 'function') {
+    return validationMessage;
+  }
+  return () => validationMessage;
+};
 export const removeValueFromSelectedOptions = (selectedOptions, value) => {
   return selectedOptions.filter(option => {
     if (Array.isArray(value)) {