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

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

@@ -26,22 +26,6 @@ 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/dist/Form/SelectDropdown/SelectDropdown.js

@@ -1,14 +1,28 @@
 import { useTheme } from '@emotion/react';
-import { useId, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
 import * as React from 'react';
-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 { 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 { 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.
  *
@@ -59,58 +73,101 @@ export const SelectDropdown = ({
   disabled,
   dropdownWidth,
   error,
-  formatCreateLabel = inputValue => `Add "${inputValue}"`,
   id,
   inputProps,
   inputWidth,
-  isCreatable = false,
-  isSearchable: isSearchableProp = false,
-  isValidNewOption,
+  isSearchable = false,
   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 [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 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 theme = useTheme();
   const memoizedStyles = useMemo(() => {
     return getMemoizedStyles(theme, zIndex);
@@ -123,15 +180,14 @@ 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,
@@ -140,15 +196,12 @@ 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,
@@ -157,8 +210,7 @@ export const SelectDropdown = ({
       styles: memoizedStyles,
       value: multiple ? multiValues : parsedValue,
       onChange: changeHandler,
-      onInputChange: onInputChange,
-      onKeyDown: multiple ? keyPressHandler : undefined,
+      onKeyDown: multiple ? e => keyPressHandler(e) : undefined,
       ...rest
     })
   });

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

@@ -15,6 +15,14 @@ export declare const indicatorIcons: {
         size: number;
         icon: import("react").ForwardRefExoticComponent<import("@codecademy/gamut-icons").GamutIconProps & import("react").RefAttributes<SVGSVGElement>>;
     };
+    smallSearchable: {
+        size: number;
+        icon: import("react").ForwardRefExoticComponent<import("@codecademy/gamut-icons").GamutIconProps & import("react").RefAttributes<SVGSVGElement>>;
+    };
+    mediumSearchable: {
+        size: number;
+        icon: import("react").ForwardRefExoticComponent<import("@codecademy/gamut-icons").GamutIconProps & import("react").RefAttributes<SVGSVGElement>>;
+    };
     smallRemove: {
         size: number;
         icon: import("react").ForwardRefExoticComponent<import("@codecademy/gamut-icons").GamutIconProps & import("react").RefAttributes<SVGSVGElement>>;

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

@@ -1,4 +1,4 @@
-import { ArrowChevronDownIcon, CloseIcon, MiniChevronDownIcon, MiniDeleteIcon } from '@codecademy/gamut-icons';
+import { ArrowChevronDownIcon, CloseIcon, MiniChevronDownIcon, MiniDeleteIcon, SearchIcon } from '@codecademy/gamut-icons';
 export const iconSize = {
   small: 12,
   medium: 16
@@ -16,6 +16,14 @@ export const indicatorIcons = {
     size: iconSize.medium,
     icon: ArrowChevronDownIcon
   },
+  smallSearchable: {
+    size: iconSize.small,
+    icon: SearchIcon
+  },
+  mediumSearchable: {
+    size: iconSize.medium,
+    icon: SearchIcon
+  },
   smallRemove: {
     size: iconSize.small,
     icon: MiniDeleteIcon

package/dist/Form/SelectDropdown/elements/containers.d.ts

@@ -24,10 +24,6 @@ export declare const CustomValueContainer: ({ ...rest }: CustomSelectComponentPr
 export declare const CustomInput: ({ ...rest }: CustomSelectComponentProps<typeof SelectDropdownElements.Input>) => import("react/jsx-runtime").JSX.Element;
 /**
  * Typed wrapper around react-select component.
- * Renders CreatableSelect when isCreatable is true, ReactSelect otherwise.
- * Creatable-only props (formatCreateLabel, isValidNewOption) are stripped from
- * the non-creatable path so they don't reach ReactSelect. `onCreateOption` is
- * handled in SelectDropdown's changeHandler — do not pass it to CreatableSelect
- * or react-select will skip onChange on create.
+ * Provides type safety for the underlying react-select implementation.
  */
-export declare function TypedReactSelect<OptionType, IsMulti extends boolean = false, GroupType extends GroupBase<OptionType> = GroupBase<OptionType>>({ selectRef, isCreatable, formatCreateLabel, isValidNewOption, ...props }: Props<OptionType, IsMulti, GroupType> & TypedReactSelectProps): import("react/jsx-runtime").JSX.Element;
+export declare function TypedReactSelect<OptionType, IsMulti extends boolean = false, GroupType extends GroupBase<OptionType> = GroupBase<OptionType>>({ selectRef, ...props }: Props<OptionType, IsMulti, GroupType> & TypedReactSelectProps): import("react/jsx-runtime").JSX.Element;

package/dist/Form/SelectDropdown/elements/containers.js

@@ -1,6 +1,5 @@
 import { createContext, useLayoutEffect } from 'react';
 import ReactSelect, { components as SelectDropdownElements } from 'react-select';
-import CreatableSelect from 'react-select/creatable';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * React context for sharing state between SelectDropdown components.
@@ -117,27 +116,12 @@ export const CustomInput = ({
 
 /**
  * Typed wrapper around react-select component.
- * Renders CreatableSelect when isCreatable is true, ReactSelect otherwise.
- * Creatable-only props (formatCreateLabel, isValidNewOption) are stripped from
- * the non-creatable path so they don't reach ReactSelect. `onCreateOption` is
- * handled in SelectDropdown's changeHandler — do not pass it to CreatableSelect
- * or react-select will skip onChange on create.
+ * Provides type safety for the underlying react-select implementation.
  */
 export function TypedReactSelect({
   selectRef,
-  isCreatable,
-  formatCreateLabel,
-  isValidNewOption,
   ...props
 }) {
-  if (isCreatable) {
-    return /*#__PURE__*/_jsx(CreatableSelect, {
-      ...props,
-      formatCreateLabel: formatCreateLabel,
-      isValidNewOption: isValidNewOption,
-      ref: selectRef
-    });
-  }
   return /*#__PURE__*/_jsx(ReactSelect, {
     ...props,
     ref: selectRef

package/dist/Form/SelectDropdown/elements/controls.d.ts

@@ -1,6 +1,20 @@
-import { SizedIndicatorProps } from '../types';
+import { AriaOnFocus } from 'react-select';
+import { ExtendedOption, SizedIndicatorProps } from '../types';
+/**
+ * Generates accessible focus messages for screen readers.
+ * Provides detailed information about the currently focused option.
+ *
+ * @param params - Object containing the focused option details
+ * @returns Formatted accessibility message
+ */
+export declare const onFocus: AriaOnFocus<ExtendedOption>;
 /**
  * Custom dropdown indicator that shows either a chevron or search icon.
  * The icon type depends on whether the select is searchable or not.
  */
 export declare const DropdownButton: (props: SizedIndicatorProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Custom remove all button for multi-select mode.
+ * Provides keyboard navigation and accessible removal of all selected values.
+ */
+export declare const RemoveAllButton: (props: SizedIndicatorProps) => import("react/jsx-runtime").JSX.Element;

package/dist/Form/SelectDropdown/elements/controls.js

@@ -1,23 +1,50 @@
+import _styled from "@emotion/styled/base";
+import { css, theme } from '@codecademy/gamut-styles';
+import { useContext } from 'react';
 import { components as SelectDropdownElements } from 'react-select';
 import { indicatorIcons } from './constants';
+import { SelectDropdownContext } from './containers';
 import { jsx as _jsx } from "react/jsx-runtime";
 const {
   DropdownIndicator
 } = SelectDropdownElements;
 
+/**
+ * Generates accessible focus messages for screen readers.
+ * Provides detailed information about the currently focused option.
+ *
+ * @param params - Object containing the focused option details
+ * @returns Formatted accessibility message
+ */
+export const onFocus = ({
+  focused: {
+    label,
+    subtitle,
+    rightLabel,
+    disabled
+  }
+}) => {
+  const formattedSubtitle = `, ${subtitle}`;
+  const formattedRightLabel = `, ${rightLabel}`;
+  const msg = `You are currently focused on option ${label}${subtitle ? formattedSubtitle : ''} ${rightLabel ? formattedRightLabel : ''}${disabled ? ', disabled' : ''}`;
+  return msg;
+};
+
 /**
  * Custom dropdown indicator that shows either a chevron or search icon.
  * The icon type depends on whether the select is searchable or not.
  */
 export const DropdownButton = props => {
   const {
-    size
+    size,
+    isSearchable
   } = props.selectProps;
   const color = props.isDisabled ? 'text-disabled' : 'text';
   const iconSize = size ?? 'medium';
+  const iconType = isSearchable ? 'Searchable' : 'Chevron';
   const {
     ...iconProps
-  } = indicatorIcons[`${iconSize}Chevron`];
+  } = indicatorIcons[`${iconSize}${iconType}`];
   const {
     icon: IndicatorIcon
   } = iconProps;
@@ -28,4 +55,66 @@ export const DropdownButton = props => {
       color: color
     })
   });
+};
+const CustomStyledRemoveAllDiv = /*#__PURE__*/_styled('div', {
+  target: "e1xkmr70",
+  label: "CustomStyledRemoveAllDiv"
+})(css({
+  '&:focus': {
+    outline: `2px solid ${theme.colors.primary}`
+  },
+  '&:focus-visible': {
+    outline: `2px solid ${theme.colors.primary}`
+  }
+}), process.env.NODE_ENV === "production" ? "" : "/*# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9Gb3JtL1NlbGVjdERyb3Bkb3duL2VsZW1lbnRzL2NvbnRyb2xzLnRzeCJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFxRGlDIiwiZmlsZSI6Ii4uLy4uLy4uLy4uL3NyYy9Gb3JtL1NlbGVjdERyb3Bkb3duL2VsZW1lbnRzL2NvbnRyb2xzLnRzeCIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCB7IGNzcywgdGhlbWUgfSBmcm9tICdAY29kZWNhZGVteS9nYW11dC1zdHlsZXMnO1xuaW1wb3J0IHN0eWxlZCBmcm9tICdAZW1vdGlvbi9zdHlsZWQnO1xuaW1wb3J0IHsgS2V5Ym9hcmRFdmVudCwgdXNlQ29udGV4dCB9IGZyb20gJ3JlYWN0JztcbmltcG9ydCB7XG4gIEFyaWFPbkZvY3VzLFxuICBjb21wb25lbnRzIGFzIFNlbGVjdERyb3Bkb3duRWxlbWVudHMsXG59IGZyb20gJ3JlYWN0LXNlbGVjdCc7XG5cbmltcG9ydCB7IEV4dGVuZGVkT3B0aW9uLCBTaXplZEluZGljYXRvclByb3BzIH0gZnJvbSAnLi4vdHlwZXMnO1xuaW1wb3J0IHsgaW5kaWNhdG9ySWNvbnMgfSBmcm9tICcuL2NvbnN0YW50cyc7XG5pbXBvcnQgeyBTZWxlY3REcm9wZG93bkNvbnRleHQgfSBmcm9tICcuL2NvbnRhaW5lcnMnO1xuXG5jb25zdCB7IERyb3Bkb3duSW5kaWNhdG9yIH0gPSBTZWxlY3REcm9wZG93bkVsZW1lbnRzO1xuXG4vKipcbiAqIEdlbmVyYXRlcyBhY2Nlc3NpYmxlIGZvY3VzIG1lc3NhZ2VzIGZvciBzY3JlZW4gcmVhZGVycy5cbiAqIFByb3ZpZGVzIGRldGFpbGVkIGluZm9ybWF0aW9uIGFib3V0IHRoZSBjdXJyZW50bHkgZm9jdXNlZCBvcHRpb24uXG4gKlxuICogQHBhcmFtIHBhcmFtcyAtIE9iamVjdCBjb250YWluaW5nIHRoZSBmb2N1c2VkIG9wdGlvbiBkZXRhaWxzXG4gKiBAcmV0dXJucyBGb3JtYXR0ZWQgYWNjZXNzaWJpbGl0eSBtZXNzYWdlXG4gKi9cbmV4cG9ydCBjb25zdCBvbkZvY3VzOiBBcmlhT25Gb2N1czxFeHRlbmRlZE9wdGlvbj4gPSAoe1xuICBmb2N1c2VkOiB7IGxhYmVsLCBzdWJ0aXRsZSwgcmlnaHRMYWJlbCwgZGlzYWJsZWQgfSxcbn0pID0+IHtcbiAgY29uc3QgZm9ybWF0dGVkU3VidGl0bGUgPSBgLCAke3N1YnRpdGxlfWA7XG4gIGNvbnN0IGZvcm1hdHRlZFJpZ2h0TGFiZWwgPSBgLCAke3JpZ2h0TGFiZWx9YDtcblxuICBjb25zdCBtc2cgPSBgWW91IGFyZSBjdXJyZW50bHkgZm9jdXNlZCBvbiBvcHRpb24gJHtsYWJlbH0ke1xuICAgIHN1YnRpdGxlID8gZm9ybWF0dGVkU3VidGl0bGUgOiAnJ1xuICB9ICR7cmlnaHRMYWJlbCA/IGZvcm1hdHRlZFJpZ2h0TGFiZWwgOiAnJ30ke2Rpc2FibGVkID8gJywgZGlzYWJsZWQnIDogJyd9YDtcblxuICByZXR1cm4gbXNnO1xufTtcblxuLyoqXG4gKiBDdXN0b20gZHJvcGRvd24gaW5kaWNhdG9yIHRoYXQgc2hvd3MgZWl0aGVyIGEgY2hldnJvbiBvciBzZWFyY2ggaWNvbi5cbiAqIFRoZSBpY29uIHR5cGUgZGVwZW5kcyBvbiB3aGV0aGVyIHRoZSBzZWxlY3QgaXMgc2VhcmNoYWJsZSBvciBub3QuXG4gKi9cbmV4cG9ydCBjb25zdCBEcm9wZG93bkJ1dHRvbiA9IChwcm9wczogU2l6ZWRJbmRpY2F0b3JQcm9wcykgPT4ge1xuICBjb25zdCB7IHNpemUsIGlzU2VhcmNoYWJsZSB9ID0gcHJvcHMuc2VsZWN0UHJvcHM7XG4gIGNvbnN0IGNvbG9yID0gcHJvcHMuaXNEaXNhYmxlZCA/ICd0ZXh0LWRpc2FibGVkJyA6ICd0ZXh0JztcbiAgY29uc3QgaWNvblNpemUgPSBzaXplID8/ICdtZWRpdW0nO1xuICBjb25zdCBpY29uVHlwZSA9IGlzU2VhcmNoYWJsZSA/ICdTZWFyY2hhYmxlJyA6ICdDaGV2cm9uJztcbiAgY29uc3QgeyAuLi5pY29uUHJvcHMgfSA9IGluZGljYXRvckljb25zW2Ake2ljb25TaXplfSR7aWNvblR5cGV9YF07XG4gIGNvbnN0IHsgaWNvbjogSW5kaWNhdG9ySWNvbiB9ID0gaWNvblByb3BzO1xuXG4gIHJldHVybiAoXG4gICAgPERyb3Bkb3duSW5kaWNhdG9yIHsuLi5wcm9wc30+XG4gICAgICA8SW5kaWNhdG9ySWNvbiB7Li4uaWNvblByb3BzfSBjb2xvcj17Y29sb3J9IC8+XG4gICAgPC9Ecm9wZG93bkluZGljYXRvcj5cbiAgKTtcbn07XG5cbmNvbnN0IEN1c3RvbVN0eWxlZFJlbW92ZUFsbERpdiA9IHN0eWxlZCgnZGl2JykoXG4gIGNzcyh7XG4gICAgJyY6Zm9jdXMnOiB7XG4gICAgICBvdXRsaW5lOiBgMnB4IHNvbGlkICR7dGhlbWUuY29sb3JzLnByaW1hcnl9YCxcbiAgICB9LFxuICAgICcmOmZvY3VzLXZpc2libGUnOiB7XG4gICAgICBvdXRsaW5lOiBgMnB4IHNvbGlkICR7dGhlbWUuY29sb3JzLnByaW1hcnl9YCxcbiAgICB9LFxuICB9KVxuKTtcblxuLyoqXG4gKiBDdXN0b20gcmVtb3ZlIGFsbCBidXR0b24gZm9yIG11bHRpLXNlbGVjdCBtb2RlLlxuICogUHJvdmlkZXMga2V5Ym9hcmQgbmF2aWdhdGlvbiBhbmQgYWNjZXNzaWJsZSByZW1vdmFsIG9mIGFsbCBzZWxlY3RlZCB2YWx1ZXMuXG4gKi9cbmV4cG9ydCBjb25zdCBSZW1vdmVBbGxCdXR0b24gPSAocHJvcHM6IFNpemVkSW5kaWNhdG9yUHJvcHMpID0+IHtcbiAgY29uc3Qge1xuICAgIGdldFN0eWxlcyxcbiAgICBpbm5lclByb3BzOiB7IC4uLnJlc3RJbm5lclByb3BzIH0sXG4gICAgc2VsZWN0UHJvcHM6IHsgc2l6ZSB9LFxuICB9ID0gcHJvcHM7XG5cbiAgY29uc3QgeyByZW1vdmVBbGxCdXR0b25SZWYsIHNlbGVjdElucHV0UmVmIH0gPSB1c2VDb250ZXh0KFxuICAgIFNlbGVjdERyb3Bkb3duQ29udGV4dFxuICApO1xuXG4gIGNvbnN0IGljb25TaXplID0gc2l6ZSA/PyAnbWVkaXVtJztcbiAgY29uc3QgeyAuLi5pY29uUHJvcHMgfSA9IGluZGljYXRvckljb25zW2Ake2ljb25TaXplfVJlbW92ZWBdO1xuICBjb25zdCB7IGljb246IEluZGljYXRvckljb24gfSA9IGljb25Qcm9wcztcblxuICBjb25zdCBvbktleVByZXNzID0gKGU6IEtleWJvYXJkRXZlbnQ8SFRNTERpdkVsZW1lbnQ+KSA9PiB7XG4gICAgaWYgKGUua2V5ID09PSAnRW50ZXInICYmIHJlc3RJbm5lclByb3BzLm9uTW91c2VEb3duKSB7XG4gICAgICByZXN0SW5uZXJQcm9wcy5vbk1vdXNlRG93bihlIGFzIGFueSk7XG4gICAgfVxuXG4gICAgaWYgKFxuICAgICAgc2VsZWN0SW5wdXRSZWY/LmN1cnJlbnQgJiZcbiAgICAgIChlLmtleSA9PT0gJ0Fycm93UmlnaHQnIHx8IGUua2V5ID09PSAnQXJyb3dMZWZ0JyB8fCBlLmtleSA9PT0gJ0Fycm93RG93bicpXG4gICAgKSB7XG4gICAgICBzZWxlY3RJbnB1dFJlZj8uY3VycmVudC5mb2N1cygpO1xuICAgIH1cbiAgfTtcblxuICBjb25zdCBzdHlsZSA9IGdldFN0eWxlcygnY2xlYXJJbmRpY2F0b3InLCBwcm9wcykgYXMgUmVhY3QuQ1NTUHJvcGVydGllcztcblxuICByZXR1cm4gKFxuICAgIDxDdXN0b21TdHlsZWRSZW1vdmVBbGxEaXZcbiAgICAgIGFyaWEtbGFiZWw9XCJSZW1vdmUgYWxsIHNlbGVjdGVkXCJcbiAgICAgIHJvbGU9XCJidXR0b25cIlxuICAgICAgdGFiSW5kZXg9ezB9XG4gICAgICB7Li4ucmVzdElubmVyUHJvcHN9XG4gICAgICByZWY9e3JlbW92ZUFsbEJ1dHRvblJlZn1cbiAgICAgIC8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBnYW11dC9uby1pbmxpbmUtc3R5bGVcbiAgICAgIHN0eWxlPXtzdHlsZX1cbiAgICAgIG9uS2V5RG93bj17b25LZXlQcmVzc31cbiAgICA+XG4gICAgICA8SW5kaWNhdG9ySWNvbiB7Li4uaWNvblByb3BzfSBjb2xvcj1cInRleHRcIiAvPlxuICAgIDwvQ3VzdG9tU3R5bGVkUmVtb3ZlQWxsRGl2PlxuICApO1xufTtcbiJdfQ== */");
+
+/**
+ * Custom remove all button for multi-select mode.
+ * Provides keyboard navigation and accessible removal of all selected values.
+ */
+export const RemoveAllButton = props => {
+  const {
+    getStyles,
+    innerProps: {
+      ...restInnerProps
+    },
+    selectProps: {
+      size
+    }
+  } = props;
+  const {
+    removeAllButtonRef,
+    selectInputRef
+  } = useContext(SelectDropdownContext);
+  const iconSize = size ?? 'medium';
+  const {
+    ...iconProps
+  } = indicatorIcons[`${iconSize}Remove`];
+  const {
+    icon: IndicatorIcon
+  } = iconProps;
+  const onKeyPress = e => {
+    if (e.key === 'Enter' && restInnerProps.onMouseDown) {
+      restInnerProps.onMouseDown(e);
+    }
+    if (selectInputRef?.current && (e.key === 'ArrowRight' || e.key === 'ArrowLeft' || e.key === 'ArrowDown')) {
+      selectInputRef?.current.focus();
+    }
+  };
+  const style = getStyles('clearIndicator', props);
+  return /*#__PURE__*/_jsx(CustomStyledRemoveAllDiv, {
+    "aria-label": "Remove all selected",
+    role: "button",
+    tabIndex: 0,
+    ...restInnerProps,
+    ref: removeAllButtonRef
+    // eslint-disable-next-line gamut/no-inline-style
+    ,
+    style: style,
+    onKeyDown: onKeyPress,
+    children: /*#__PURE__*/_jsx(IndicatorIcon, {
+      ...iconProps,
+      color: "text"
+    })
+  });
 };

package/dist/Form/SelectDropdown/elements/index.d.ts

@@ -1,6 +1,5 @@
 export { iconSize, selectedIconSize, indicatorIcons } from './constants';
 export { MultiValueWithColorMode, MultiValueRemoveButton, RemoveAllButton, } from './multi-value';
-export { DropdownButton } from './controls';
-export { onFocus } from '../core/accessibility';
+export { DropdownButton, onFocus } from './controls';
 export { SelectDropdownContext, CustomContainer, CustomInput, CustomValueContainer, TypedReactSelect, } from './containers';
 export { IconOption, AbbreviatedSingleValue, formatOptionLabel, formatGroupLabel, } from './options';

package/dist/Form/SelectDropdown/elements/index.js

@@ -1,6 +1,5 @@
 export { iconSize, selectedIconSize, indicatorIcons } from './constants';
 export { MultiValueWithColorMode, MultiValueRemoveButton, RemoveAllButton } from './multi-value';
-export { DropdownButton } from './controls';
-export { onFocus } from '../core/accessibility';
+export { DropdownButton, onFocus } from './controls';
 export { SelectDropdownContext, CustomContainer, CustomInput, CustomValueContainer, TypedReactSelect } from './containers';
 export { IconOption, AbbreviatedSingleValue, formatOptionLabel, formatGroupLabel } from './options';

package/dist/Form/SelectDropdown/elements/options.d.ts

@@ -3,7 +3,6 @@ import { CustomSelectComponentProps, ExtendedOption, SelectDropdownGroup } from
 /**
  * Custom option component that displays a check icon for selected items.
  * Also manages ARIA attributes for accessibility.
- * Skips the check icon for react-select/creatable's "Add" row (__isNew__).
  */
 export declare const IconOption: ({ children, ...rest }: CustomSelectComponentProps<typeof SelectDropdownElements.Option>) => import("react/jsx-runtime").JSX.Element;
 /**

package/dist/Form/SelectDropdown/elements/options.js

@@ -44,7 +44,6 @@ const IconOptionLabel = ({
 /**
  * Custom option component that displays a check icon for selected items.
  * Also manages ARIA attributes for accessibility.
- * Skips the check icon for react-select/creatable's "Add" row (__isNew__).
  */
 export const IconOption = ({
   children,
@@ -55,17 +54,15 @@ export const IconOption = ({
   } = rest.selectProps;
   const {
     isFocused,
-    innerProps,
-    data
+    innerProps
   } = rest;
-  const isNew = data?.__isNew__;
   return /*#__PURE__*/_jsxs(SelectDropdownElements.Option, {
     ...rest,
     innerProps: {
       ...innerProps,
       'aria-selected': isFocused
     },
-    children: [children, !isNew && rest?.isSelected && /*#__PURE__*/_jsx(CheckIcon, {
+    children: [children, rest?.isSelected && /*#__PURE__*/_jsx(CheckIcon, {
       size: selectedIconSize[size ?? 'medium']
     })]
   });

package/dist/Form/SelectDropdown/{core/styles.js → 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-secondary'
+  color: 'text-disabled'
 });
 export const getMemoizedStyles = (theme, zIndex) => {
   return {
@@ -137,8 +137,6 @@ 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
@@ -196,32 +194,16 @@ export const getMemoizedStyles = (theme, zIndex) => {
         backgroundColor: theme.colors['secondary-hover']
       }
     }),
-    noOptionsMessage: provided => ({
-      ...provided,
-      color: theme.colors['text-secondary']
+    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'
     }),
-    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/types/component-props.d.ts

@@ -1,5 +1,5 @@
 import { Ref, SelectHTMLAttributes } from 'react';
-import { Options as OptionsType, Props as NamedProps } from 'react-select';
+import { Props as NamedProps } from 'react-select';
 import { SelectComponentProps } from '../../inputs/Select';
 import { OptionStrict, SelectDropdownGroup, SelectDropdownOptions } from './options';
 import { ReactSelectAdditionalProps, SelectDropdownSizes, SharedProps } from './styles';
@@ -28,7 +28,7 @@ export type SelectDropdownBaseProps = Omit<SelectComponentProps, 'onChange' | 'd
  * Core props interface that defines the essential properties for SelectDropdown.
  * This interface combines base props with react-select props and HTML select attributes.
  */
-export interface SelectDropdownCoreProps extends SelectDropdownBaseProps, Omit<NamedProps<OptionStrict, boolean>, 'formatOptionLabel' | 'isDisabled' | 'value' | 'options' | 'components' | 'styles' | 'theme' | 'onChange' | 'multiple' | 'isSearchable'>, Pick<SelectHTMLAttributes<HTMLSelectElement>, 'value' | 'disabled' | 'onClick'>, SharedProps {
+export interface SelectDropdownCoreProps extends SelectDropdownBaseProps, Omit<NamedProps<OptionStrict, boolean>, 'formatOptionLabel' | 'isDisabled' | 'value' | 'options' | 'components' | 'styles' | 'theme' | 'onChange' | 'multiple'>, Pick<SelectHTMLAttributes<HTMLSelectElement>, 'value' | 'disabled' | 'onClick'>, SharedProps {
     /** Required name attribute for the select input */
     name: string;
     /** Placeholder text shown when no option is selected.
@@ -38,39 +38,6 @@ export interface SelectDropdownCoreProps extends SelectDropdownBaseProps, Omit<N
     placeholder?: string;
     /** Array of options or option groups to display in the dropdown */
     options?: SelectDropdownOptions | SelectDropdownGroup[];
-    /**
-     * Allows users to create new options by typing a value not in the options list.
-     * When true, isSearchable is automatically set to true.
-     * Pair with onCreateOption to persist new options.
-     */
-    isCreatable?: boolean;
-    /**
-     * Called when the user confirms a new option via the "Add" row.
-     * Convenience callback for persisting the new value to your `options` list.
-     * Selection updates are delivered through `onChange` with `action: 'create-option'`.
-     */
-    onCreateOption?: (inputValue: string) => void;
-    /**
-     * Customises the label shown in the "Add" row.
-     * Defaults to: (inputValue) => `Add "${inputValue}"`.
-     */
-    formatCreateLabel?: (inputValue: string) => React.ReactNode;
-    /**
-     * Controls when the "Add" row is visible.
-     * Receives the current input, selected values, and all options.
-     * Defaults to react-select's built-in logic (hidden when input matches an existing option label).
-     * Use cases: minimum-length gating, pattern validation, case-insensitive dedup, max-items cap.
-     */
-    isValidNewOption?: (inputValue: string, value: OptionsType<OptionStrict>, options: OptionsType<OptionStrict>) => boolean;
-    /**
-     * Customizes the message shown inside the dropdown menu when no option matches
-     * the current input (react-select's "No options" state). Useful for surfacing
-     * validation/error text directly in the dropdown. Accepts a node, or a function
-     * receiving the current input value.
-     */
-    validationMessage?: React.ReactNode | ((obj: {
-        inputValue: string;
-    }) => React.ReactNode);
 }
 /**
  * Props for single-select mode.
@@ -92,23 +59,11 @@ export interface MultiSelectDropdownProps extends SelectDropdownCoreProps {
     /** Callback fired when the selected values change */
     onChange?: NamedProps<OptionStrict, true>['onChange'];
 }
-/**
- * Enforces that isSearchable cannot be false when isCreatable is true.
- * Creatable mode requires the search input so users can type new option values.
- */
-type CreatableConstraint = {
-    isCreatable?: false | undefined;
-    isSearchable?: boolean;
-} | {
-    isCreatable: true;
-    isSearchable?: true;
-};
 /**
  * Union type for all SelectDropdown prop variants.
- * Supports both single and multi-select modes through discriminated union,
- * intersected with CreatableConstraint to enforce isSearchable compatibility.
+ * Supports both single and multi-select modes through discriminated union.
  */
-export type SelectDropdownProps = (SingleSelectDropdownProps | MultiSelectDropdownProps) & CreatableConstraint;
+export type SelectDropdownProps = SingleSelectDropdownProps | MultiSelectDropdownProps;
 /**
  * Base interface for onChange-related props.
  * Used internally for type checking and prop validation.
@@ -121,12 +76,9 @@ export interface BaseOnChangeProps {
 }
 /**
  * Props for the typed React Select component wrapper.
- * Extends ReactSelectAdditionalProps with an optional ref and creatable flag.
+ * Extends ReactSelectAdditionalProps with an optional ref.
  */
-export interface TypedReactSelectProps extends ReactSelectAdditionalProps, Pick<SelectDropdownCoreProps, 'formatCreateLabel' | 'isValidNewOption'> {
+export interface TypedReactSelectProps extends ReactSelectAdditionalProps {
     /** Optional ref to the underlying react-select component */
     selectRef?: Ref<any>;
-    /** When true, renders CreatableSelect instead of ReactSelect */
-    isCreatable?: boolean;
 }
-export {};

package/dist/Form/SelectDropdown/types/internal.d.ts

@@ -14,7 +14,7 @@ export type InternalSelectProps = {
  * Ref type for programmatic focus management.
  * Used for managing focus on select input and remove all button.
  */
-export type ProgrammaticFocusRef = React.MutableRefObject<HTMLDivElement> | React.MutableRefObject<null>;
+export type ProgramaticFocusRef = React.MutableRefObject<HTMLDivElement> | React.MutableRefObject<null>;
 /**
  * Context value for SelectDropdown internal state management.
  * Provides access to focus state and refs for keyboard navigation.
@@ -25,9 +25,9 @@ export interface SelectDropdownContextValueTypes {
     /** Function to update the currently focused value */
     setCurrentFocusedValue?: React.Dispatch<React.SetStateAction<unknown>>;
     /** Ref to the select input for programmatic focus */
-    selectInputRef?: ProgrammaticFocusRef;
+    selectInputRef?: ProgramaticFocusRef;
     /** Ref to the remove all button for programmatic focus */
-    removeAllButtonRef?: ProgrammaticFocusRef;
+    removeAllButtonRef?: ProgramaticFocusRef;
 }
 /**
  * Props for sized indicator components (dropdown arrow, search icon, etc.).

package/dist/Form/SelectDropdown/types/styles.d.ts

@@ -1,5 +1,5 @@
 import { StyleProps } from '@codecademy/variance';
-import { conditionalBorderStates } from '../core/styles';
+import { conditionalBorderStates } from '../styles';
 import { InternalInputsProps } from './component-props';
 /**
  * Size variants for the SelectDropdown component.
@@ -69,9 +69,5 @@ export type ControlState = BaseSelectComponentProps & InteractionStates & {
 export type OptionState = BaseSelectComponentProps & InteractionStates & {
     /** Whether the option is selected */
     isSelected: boolean;
-    /** Option data — includes __isNew__ for react-select/creatable's "Add" row */
-    data?: {
-        __isNew__?: boolean;
-    };
 };
 export {};

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

@@ -1,14 +1,7 @@
-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';
+import { SelectOptionBase } from '../utils';
+import { BaseOnChangeProps, ExtendedOption, MultiSelectDropdownProps, 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[];
 /**
@@ -30,7 +23,4 @@ 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/{core/utils.js → utils.js}

@@ -1,21 +1,5 @@
 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));
 
@@ -44,13 +28,6 @@ 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)) {

package/dist/Form/styles/index.d.ts

@@ -1,4 +1,4 @@
 export * from './shared-system-props';
 export * from './Checkbox-styles';
 export * from './Radio-styles';
-export * from '../SelectDropdown/core/styles';
+export * from '../SelectDropdown/styles';

package/dist/Form/styles/index.js

@@ -1,4 +1,4 @@
 export * from './shared-system-props';
 export * from './Checkbox-styles';
 export * from './Radio-styles';
-export * from '../SelectDropdown/core/styles';
+export * from '../SelectDropdown/styles';

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@codecademy/gamut",
   "description": "Styleguide & Component library for Codecademy",
-  "version": "72.2.3-alpha.f0a032.0",
+  "version": "72.2.3-alpha.f2e313.0",
   "author": "Codecademy Engineering <dev@codecademy.com>",
   "bin": "./bin/gamut.mjs",
   "dependencies": {
-    "@codecademy/gamut-icons": "9.57.10-alpha.f0a032.0",
-    "@codecademy/gamut-illustrations": "0.58.16-alpha.f0a032.0",
-    "@codecademy/gamut-patterns": "0.10.35-alpha.f0a032.0",
-    "@codecademy/gamut-styles": "20.0.3-alpha.f0a032.0",
-    "@codecademy/variance": "0.26.2-alpha.f0a032.0",
+    "@codecademy/gamut-icons": "9.57.10-alpha.f2e313.0",
+    "@codecademy/gamut-illustrations": "0.58.16-alpha.f2e313.0",
+    "@codecademy/gamut-patterns": "0.10.35-alpha.f2e313.0",
+    "@codecademy/gamut-styles": "20.0.3-alpha.f2e313.0",
+    "@codecademy/variance": "0.26.2-alpha.f2e313.0",
     "@formatjs/intl-locale": "5.3.1",
     "@react-aria/interactions": "3.25.0",
     "@types/marked": "^4.0.8",

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

@@ -1,236 +0,0 @@
----
-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/Form/SelectDropdown/core/accessibility.d.ts

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

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

@@ -1,12 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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/hooks/useSelectHandlers.d.ts

@@ -1,22 +0,0 @@
-import { KeyboardEvent } from 'react';
-import * as React from 'react';
-import { ActionMeta, Options as OptionsType } from 'react-select';
-import { SelectOptionBase } from '../../utils';
-import { MultiSelectDropdownProps, OptionStrict, SelectDropdownGroup, SelectDropdownProps, SingleSelectDropdownProps } from '../types';
-interface UseSelectHandlersArgs {
-    onChange?: SingleSelectDropdownProps['onChange'] | MultiSelectDropdownProps['onChange'];
-    multiple?: boolean;
-    onCreateOption?: (inputValue: string) => void;
-    selectOptions: SelectOptionBase[] | SelectDropdownGroup[];
-    value?: SelectDropdownProps['value'];
-    currentFocusedValue: unknown;
-    removeAllButtonRef: React.MutableRefObject<HTMLDivElement | null>;
-}
-interface UseSelectHandlersReturn {
-    activated: boolean;
-    multiValues: OptionStrict[] | false;
-    changeHandler: (optionEvent: OptionStrict | OptionsType<OptionStrict>, actionMeta: ActionMeta<OptionStrict>) => void;
-    keyPressHandler: (e: KeyboardEvent<HTMLDivElement>) => void;
-}
-export declare const useSelectHandlers: ({ onChange, multiple, onCreateOption, selectOptions, value, currentFocusedValue, removeAllButtonRef, }: UseSelectHandlersArgs) => UseSelectHandlersReturn;
-export {};

package/dist/Form/SelectDropdown/hooks/useSelectHandlers.js

@@ -1,62 +0,0 @@
-import { useCallback, useEffect, useState } from 'react';
-import { ON_CHANGE_ACTION } from '../core/constants';
-import { filterValueFromOptions, getCreatedOptionValue, isMultipleSelectProps, isOptionsGrouped, isSingleSelectProps, removeValueFromSelectedOptions } from '../core/utils';
-export const useSelectHandlers = ({
-  onChange,
-  multiple,
-  onCreateOption,
-  selectOptions,
-  value,
-  currentFocusedValue,
-  removeAllButtonRef
-}) => {
-  const [activated, setActivated] = useState(false);
-  const [multiValues, setMultiValues] = useState(multiple ? filterValueFromOptions(selectOptions, value, isOptionsGrouped(selectOptions)) : false);
-
-  // Sync multi-select value from props when controlled (`value` is a string[]).
-  // Uncontrolled multi (`value` undefined or '') keeps selection in local state.
-  useEffect(() => {
-    if (!multiple || !Array.isArray(value)) return;
-    const newMultiValues = filterValueFromOptions(selectOptions, value, isOptionsGrouped(selectOptions));
-    if (newMultiValues !== multiValues) setMultiValues(newMultiValues);
-
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [selectOptions, value, multiple]);
-  const changeHandler = useCallback((optionEvent, actionMeta) => {
-    setActivated(true);
-    if (actionMeta.action === 'create-option') {
-      const createdValue = getCreatedOptionValue(optionEvent, actionMeta, multiple);
-      if (createdValue) onCreateOption?.(createdValue);
-    }
-    const onChangeProps = {
-      onChange,
-      multiple
-    };
-    const forwardedMeta = actionMeta.action === 'create-option' ? actionMeta : {
-      action: ON_CHANGE_ACTION,
-      option: isMultipleSelectProps(onChangeProps) ? undefined : optionEvent
-    };
-    if (isSingleSelectProps(onChangeProps)) {
-      onChangeProps.onChange?.(optionEvent, forwardedMeta);
-    }
-    if (isMultipleSelectProps(onChangeProps)) {
-      setMultiValues(optionEvent);
-      onChangeProps.onChange?.(optionEvent, forwardedMeta);
-    }
-  }, [onChange, multiple, onCreateOption]);
-  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();
-    }
-  };
-  return {
-    activated,
-    multiValues,
-    changeHandler,
-    keyPressHandler
-  };
-};

package/dist/Form/SelectDropdown/hooks/useSelectOptions.d.ts

@@ -1,14 +0,0 @@
-import { SelectOptionBase } from '../../utils';
-import { SelectDropdownGroup, SelectDropdownOptions, SelectDropdownSizes } from '../types';
-interface UseSelectOptionsArgs {
-    options?: SelectDropdownOptions | SelectDropdownGroup[];
-    id?: string;
-    size?: SelectDropdownSizes['size'];
-    value?: string | string[];
-}
-interface UseSelectOptionsReturn {
-    selectOptions: SelectOptionBase[] | SelectDropdownGroup[];
-    parsedValue: SelectOptionBase | undefined;
-}
-export declare const useSelectOptions: ({ options, id, size, value, }: UseSelectOptionsArgs) => UseSelectOptionsReturn;
-export {};

package/dist/Form/SelectDropdown/hooks/useSelectOptions.js

@@ -1,39 +0,0 @@
-import { useMemo } from 'react';
-import { parseOptions } from '../../utils';
-import { isOptionsGrouped } from '../core/utils';
-export const useSelectOptions = ({
-  options,
-  id,
-  size,
-  value
-}) => {
-  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]);
-  return {
-    selectOptions,
-    parsedValue
-  };
-};