@codecademy/gamut 72.2.4-alpha.628984.0 → 72.2.4-alpha.716ed7.0

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).
-- Rely on FormGroupLabel's `htmlFor`/`id` connection for the accessible label — this is the standard HTML pattern and preferred method.
-- Only add `aria-label` when absolutely necessary (e.g., no visible label, label is hidden, or form context requires it). Do not use `aria-label` when a FormGroupLabel is present, as it overrides the visible label.
-- 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"
-    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
-  };
-};