aplance-ui 1.3.0 → 1.5.0

package/registry/components/ui/input-fields/custom-select/custom-select.tsx

@@ -1,484 +1,552 @@
-import type { Align, Position } from "../../../primitives/popover/popover";
-import {
-  type CSSProperties,
-  type ReactNode,
-  useCallback,
-  useEffect,
-  useId,
-  useMemo,
-  useState,
-} from "react";
-import clsx from "clsx";
-import { IconPlus, IconTrash } from "@tabler/icons-react";
-import { Input } from "../input/input";
-import {
-  Popover,
-  PopoverTrigger,
-  PopoverMenu,
-} from "../../../primitives/popover/popover";
-import type { ComponentProps } from "react";
-import sCommon from "../common/input-field-common.module.css";
-import sPickerCommon from "../common/picker-popover-common.module.css";
-import { Button, type ButtonVariant } from "../../button/button";
-import s from "./custom-select.module.css";
-import { FieldMessage } from "../common/field-message/field-message";
-import { SelectButton, type SelectButtonProps } from "../common/select-button/select-button";
-import { Icon } from "../../../primitives/icon/icon";
-import type { BaseInputFieldProps } from "../common/types";
-
-export type CustomSelectOption = {
-  value: string;
-  label: string;
-  icon?: ReactNode;
-  optionStyle?: CSSProperties;
-  optionClassName?: string;
-  optionButtonVariant?: ButtonVariant;
-  applyToSelector?: boolean;
-  disabled?: boolean;
-  /** Renders a trailing delete affordance on the option row. Clicking it does
-   *  NOT select the option - the consumer typically opens a confirm dialog and
-   *  performs the deletion (e.g. removing a folder/tag from its pool). */
-  onDelete?: () => void;
-};
-
-export type CustomSelectProps = Omit<
-  BaseInputFieldProps,
-  // its used in selectButton so no need it here
-  "buttonStyle"
-> & {
-  // Select specific props
-  placeholder?: string;
-  searchPlaceholder?: string;
-  options: CustomSelectOption[];
-  value?: string | string[];
-  defaultValue?: string | string[];
-  onChange?: (value: string | string[]) => void;
-  multiple?: boolean;
-  searchable?: boolean;
-  /**
-   * Lets the user create a new option from the search term when nothing in
-   * `options` matches it. Requires `searchable`. The created value is emitted
-   * through `onChange` (and added to `selectedValues`); the consumer is
-   * responsible for persisting it / pushing it into the next `options` list.
-   */
-  allowCreate?: boolean;
-  showDisplayText?: boolean;
-  showDisplayIcon?: boolean;
-  onClear?: () => void;
-
-  // Popover behavior defaults
-  closeOnPathChange?: boolean;
-  closeOnClickOutside?: boolean;
-  animationDuration?: number;
-  position?: Position;
-  align?: Align;
-
-  // Nested popover props
-  popover?: Omit<ComponentProps<typeof Popover>, "children">;
-  popoverTrigger?: ComponentProps<typeof PopoverTrigger>;
-  popoverMenu?: ComponentProps<typeof PopoverMenu>;
-
-  // Options inside menu
-  optionsContainerClassName?: string;
-  optionsContainerStyle?: CSSProperties;
-
-  // Select button props
-  selectButton?: SelectButtonProps;
-};
-
-export const CustomSelect = ({
-  // Base props
-  label,
-  className,
-  style,
-  id,
-  info,
-  errors,
-  layout = "default",
-
-  // Select options and behavior
-  options,
-  value,
-  defaultValue,
-  onChange,
-  multiple = false,
-  searchable = false,
-  allowCreate = false,
-  showDisplayIcon = true,
-  showDisplayText = true,
-  disabled = false,
-  readOnly = false,
-  required = false,
-  onClear,
-  placeholder = "Select...",
-  searchPlaceholder = "Search options...",
-
-  // Popover behavior
-  closeOnPathChange = true,
-  closeOnClickOutside = true,
-  animationDuration = 200,
-  position = "bottom",
-  align = "start",
-
-  // Menu options props
-  optionsContainerClassName,
-  optionsContainerStyle,
-
-  // Nested popover props
-  popover,
-  popoverTrigger,
-  popoverMenu,
-  selectButton,
-}: CustomSelectProps) => {
-  const [searchTerm, setSearchTerm] = useState("");
-  const [isOpen, setIsOpen] = useState(false);
-
-  // Internal state for uncontrolled mode
-  const [internalValue, setInternalValue] = useState<string | string[]>(() => {
-    if (defaultValue !== undefined) {
-      return Array.isArray(defaultValue)
-        ? defaultValue
-        : defaultValue
-          ? [defaultValue]
-          : [];
-    }
-    return multiple ? [] : "";
-  });
-
-  const generatedId = useId();
-  const inputId = id ?? generatedId;
-  const isControlled = value !== undefined;
-  const actualValue = isControlled ? value : internalValue;
-  const interactive = !disabled && !readOnly;
-
-  // Normalize to array for consistent handling
-  const selectedValues = useMemo(
-    () =>
-      Array.isArray(actualValue)
-        ? actualValue
-        : actualValue
-          ? [actualValue]
-          : [],
-    [actualValue],
-  );
-
-  // A selected value may not exist in `options` - e.g. when `allowCreate` is
-  // on and the consumer just stores the value without pushing it back into
-  // the options list. Synthesize a "ghost" entry so the trigger displays it,
-  // the menu shows it (multi-select can uncheck), and the "Create" check
-  // doesn't redundantly offer something already selected.
-  const optionsWithSelected = useMemo(() => {
-    if (selectedValues.length === 0) return options;
-    const known = new Set(options.map((option) => option.value));
-    const ghosts = selectedValues
-      .filter((value) => !known.has(value))
-      .map<CustomSelectOption>((value) => ({ value, label: value }));
-    return ghosts.length > 0 ? [...ghosts, ...options] : options;
-  }, [options, selectedValues]);
-
-  // Filter options based on search
-  const filteredOptions = useMemo(
-    () =>
-      searchable && searchTerm
-        ? optionsWithSelected.filter((option) =>
-            option.label.toLowerCase().includes(searchTerm.toLowerCase()),
-          )
-        : optionsWithSelected,
-    [optionsWithSelected, searchable, searchTerm],
-  );
-
-  // "Create '<term>'" appears when allowCreate is on and the typed term
-  // doesn't match any existing option (by label or value, case-insensitive).
-  const trimmedTerm = searchTerm.trim();
-  const showCreateOption =
-    allowCreate &&
-    searchable &&
-    trimmedTerm.length > 0 &&
-    !optionsWithSelected.some(
-      (option) =>
-        option.label.toLowerCase() === trimmedTerm.toLowerCase() ||
-        option.value.toLowerCase() === trimmedTerm.toLowerCase(),
-    );
-
-  // Get all selected option data in one place. `optionsWithSelected` is used
-  // for the lookup so ghost entries (selected-but-not-in-options) resolve
-  // back to a displayable label.
-  const selectedOptionData = useMemo(() => {
-    const hasValue = selectedValues.length > 0;
-    const selectedOption = optionsWithSelected.find(
-      (opt) => opt.value === selectedValues[0],
-    );
-    const isMultipleSelection = multiple && selectedValues.length > 1;
-    const singleLabel = selectedOption?.label ?? selectedValues[0];
-
-    return {
-      hasValue,
-      option: selectedOption,
-      label: singleLabel,
-      icon: selectedOption?.icon,
-      displayText: !hasValue
-        ? placeholder
-        : isMultipleSelection
-          ? `${selectedValues.length} selected`
-          : singleLabel,
-      shouldShowIcon:
-        showDisplayIcon && selectedOption?.icon && selectedValues.length === 1,
-      appliedClassName: selectedOption?.applyToSelector
-        ? selectedOption.optionClassName
-        : undefined,
-      appliedStyle: selectedOption?.applyToSelector
-        ? selectedOption.optionStyle
-        : undefined,
-    };
-  }, [multiple, optionsWithSelected, placeholder, selectedValues, showDisplayIcon]);
-
-  const popoverOnClose = popover?.onClose;
-  const handlePopoverClose = useCallback(() => {
-    setSearchTerm("");
-    popoverOnClose?.();
-  }, [popoverOnClose]);
-
-  const {
-    className: popoverClassName,
-    offset: popoverOffset = 4,
-    ...popoverRest
-  } = popover ?? {};
-
-  const {
-    className: popoverTriggerClassName,
-    style: popoverTriggerStyle,
-    ...popoverTriggerRest
-  } = popoverTrigger ?? {};
-
-  const {
-    className: popoverMenuClassName,
-    style: popoverMenuStyle,
-    ...popoverMenuRest
-  } = popoverMenu ?? {};
-
-  // Handle external value changes for controlled mode
-  useEffect(() => {
-    if (isControlled) {
-      const normalized = Array.isArray(value) ? value : value ? [value] : [];
-      const isDifferent =
-        normalized.length !== selectedValues.length ||
-        normalized.some((val, i) => val !== selectedValues[i]);
-
-      if (isDifferent && !normalized.length) {
-        onClear?.();
-      }
-    }
-  }, [value, onClear, selectedValues, isControlled]);
-
-  const handleSelect = (option: CustomSelectOption) => {
-    if (!interactive || option.disabled) return;
-
-    const optionValue = option.value;
-
-    let newValues: string | string[];
-
-    if (multiple) {
-      newValues = selectedValues.includes(optionValue)
-        ? selectedValues.filter((val) => val !== optionValue)
-        : [...selectedValues, optionValue];
-    } else {
-      newValues = optionValue;
-      setIsOpen(false);
-    }
-
-    if (!isControlled) {
-      setInternalValue(newValues);
-    }
-
-    onChange?.(newValues);
-  };
-
-  const handleClear = (e: React.MouseEvent) => {
-    e.stopPropagation();
-    if (!interactive) return;
-
-    const newValue = multiple ? [] : "";
-
-    if (!isControlled) {
-      setInternalValue(newValue);
-    }
-
-    onChange?.(newValue);
-    onClear?.();
-  };
-
-  return (
-    <div className={clsx(sCommon.container, className)} style={style}>
-      {label && (
-        <div
-          className={clsx(
-            sCommon.field_container,
-            layout !== "default" && sCommon[layout],
-          )}
-        >
-          <label className={sCommon.label} htmlFor={inputId}>
-            {label}
-          </label>
-        </div>
-      )}
-
-      <Popover
-        closeOnPathChange={closeOnPathChange}
-        closeOnClickOutside={closeOnClickOutside}
-        animationDuration={animationDuration}
-        isOpen={isOpen}
-        setIsOpen={setIsOpen}
-        position={position}
-        align={align}
-        className={clsx(sPickerCommon.picker_popover, popoverClassName)}
-        offset={popoverOffset}
-        {...popoverRest}
-        onClose={handlePopoverClose}
-      >
-        <PopoverTrigger
-          asChild
-          className={clsx(
-            sPickerCommon.picker_popover_trigger,
-            popoverTriggerClassName,
-          )}
-          style={popoverTriggerStyle}
-          disabled={disabled || readOnly}
-          {...popoverTriggerRest}
-        >
-          <SelectButton
-            disabled={disabled || readOnly}
-            required={required}
-            showClear={selectedOptionData.hasValue && interactive}
-            onClear={handleClear}
-            id={inputId}
-            className={clsx(
-              !selectedOptionData.hasValue &&
-                sPickerCommon.picker_value_placeholder,
-              selectButton?.className,
-              selectedOptionData.appliedClassName,
-            )}
-            style={{
-              ...selectButton?.style,
-              ...selectedOptionData.appliedStyle,
-            }}
-            iconStart={
-              selectedOptionData.shouldShowIcon ? (
-                <Icon>{selectedOptionData.icon}</Icon>
-              ) : undefined
-            }
-            {...selectButton}
-          >
-            {showDisplayText && (
-              <span className={clsx(s.option_label, sCommon.truncate_text)}>
-                {selectedOptionData.displayText}
-              </span>
-            )}
-          </SelectButton>
-        </PopoverTrigger>
-
-        {!disabled && !readOnly && (
-          <PopoverMenu
-            className={clsx(
-              sPickerCommon.picker_popover_menu_base,
-              s.popover_menu,
-              popoverMenuClassName,
-            )}
-            style={popoverMenuStyle}
-            {...popoverMenuRest}
-          >
-            {searchable && (
-              <div className={s.search_container}>
-                <Input
-                  type="search"
-                  placeholder={searchPlaceholder}
-                  value={searchTerm}
-                  onChange={(e) => setSearchTerm(e.target.value)}
-                  onClick={(e) => e.stopPropagation()}
-                  showClear={true}
-                  autoFocus
-                />
-              </div>
-            )}
-
-            <div
-              className={clsx(s.options_container, optionsContainerClassName)}
-              style={optionsContainerStyle}
-            >
-              {showCreateOption && (
-                <Button
-                  as="div"
-                  variant="ghost"
-                  className={s.option}
-                  onClick={() => {
-                    handleSelect({ value: trimmedTerm, label: trimmedTerm });
-                    setSearchTerm("");
-                  }}
-                >
-                  <Icon size="sm" aria-hidden="true">
-                    <IconPlus />
-                  </Icon>
-                  <span
-                    className={clsx(s.option_label, sCommon.truncate_text)}
-                  >
-                    Create &ldquo;{trimmedTerm}&rdquo;
-                  </span>
-                </Button>
-              )}
-              {filteredOptions.length === 0 && !showCreateOption ? (
-                <p className={s.no_options}>No options found</p>
-              ) : (
-                filteredOptions.map((option) => (
-                  <Button
-                    key={option.value}
-                    as="div"
-                    variant={option.optionButtonVariant || "ghost"}
-                    className={clsx(s.option, option.optionClassName)}
-                    style={option.optionStyle}
-                    isActive={selectedValues.includes(option.value)}
-                    disabled={disabled || readOnly || option.disabled}
-                    onClick={() => handleSelect(option)}
-                  >
-                    {multiple && (
-                      <Input
-                        type="checkbox"
-                        className={sCommon.option_checkbox}
-                        checked={selectedValues.includes(option.value)}
-                        disabled={disabled || readOnly || option.disabled}
-                      />
-                    )}
-                    {option.icon && option.icon}
-                    <span
-                      className={clsx(s.option_label, sCommon.truncate_text)}
-                    >
-                      {option.label}
-                    </span>
-                    {option.onDelete && interactive ? (
-                      <Icon
-                        size="sm"
-                        clickable
-                        className={s.option_delete}
-                        aria-label={`Delete ${option.label}`}
-                        onClick={(e) => {
-                          e.stopPropagation();
-                          // Close the popover BEFORE handing off - the consumer
-                          // opens a confirm dialog, which must not sit under
-                          // the still-open popover in the stacking order.
-                          setIsOpen(false);
-                          option.onDelete?.();
-                        }}
-                      >
-                        <IconTrash />
-                      </Icon>
-                    ) : null}
-                  </Button>
-                ))
-              )}
-            </div>
-          </PopoverMenu>
-        )}
-      </Popover>
-
-      <FieldMessage errors={errors} info={info} />
-    </div>
-  );
-};
+import type { Align, Position } from "../../../primitives/popover/popover";
+import {
+  type CSSProperties,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+} from "react";
+import clsx from "clsx";
+import { IconPlus, IconTrash } from "@tabler/icons-react";
+import { Input } from "../input/input";
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverMenu,
+} from "../../../primitives/popover/popover";
+import type { ComponentProps } from "react";
+import sCommon from "../common/input-field-common.module.css";
+import sPickerCommon from "../common/picker-popover-common.module.css";
+import { Button, type ButtonVariant } from "../../button/button";
+import s from "./custom-select.module.css";
+import { FieldMessage } from "../common/field-message/field-message";
+import { SelectButton, type SelectButtonProps } from "../common/select-button/select-button";
+import { Icon } from "../../../primitives/icon/icon";
+import type { BaseInputFieldProps } from "../common/types";
+
+export type CustomSelectOption = {
+  value: string;
+  label: string;
+  /** A line under the label in the menu, for an option its label alone does
+   *  not explain. It wraps, never truncates, and search matches it too; once
+   *  chosen, the select shows the label only. */
+  description?: string;
+  icon?: ReactNode;
+  /** Trailing slot after the label and before any delete affordance. The
+   *  component positions it; consumers own its visual styling. */
+  meta?: ReactNode;
+  optionStyle?: CSSProperties;
+  optionClassName?: string;
+  optionButtonVariant?: ButtonVariant;
+  applyToSelector?: boolean;
+  disabled?: boolean;
+  /** Renders a trailing delete affordance on the option row. Clicking it does
+   *  NOT select the option - the consumer typically opens a confirm dialog and
+   *  performs the deletion (e.g. removing a folder/tag from its pool). */
+  onDelete?: () => void;
+};
+
+export type CustomSelectProps = Omit<
+  BaseInputFieldProps,
+  // its used in selectButton so no need it here
+  "buttonStyle"
+> & {
+  // Select specific props
+  placeholder?: string;
+  searchPlaceholder?: string;
+  options: CustomSelectOption[];
+  value?: string | string[];
+  defaultValue?: string | string[];
+  onChange?: (value: string | string[]) => void;
+  multiple?: boolean;
+  searchable?: boolean;
+  /**
+   * Lets the user create a new option from the search term when nothing in
+   * `options` matches it. Requires `searchable`. The created value is emitted
+   * through `onChange` (and added to `selectedValues`); the consumer is
+   * responsible for persisting it / pushing it into the next `options` list.
+   */
+  allowCreate?: boolean;
+  showDisplayText?: boolean;
+  showDisplayIcon?: boolean;
+  /** What the select shows once something is chosen, in place of the chosen
+   *  label or the count: "All images" for a choice that stands for every
+   *  option. */
+  valueText?: string;
+  onClear?: () => void;
+
+  // Popover behavior defaults
+  closeOnPathChange?: boolean;
+  closeOnClickOutside?: boolean;
+  animationDuration?: number;
+  position?: Position;
+  align?: Align;
+  autoPosition?: boolean;
+  collisionPadding?: number;
+
+  // Nested popover props
+  popover?: Omit<ComponentProps<typeof Popover>, "children">;
+  popoverTrigger?: ComponentProps<typeof PopoverTrigger>;
+  popoverMenu?: ComponentProps<typeof PopoverMenu>;
+
+  // Options inside menu
+  optionsContainerClassName?: string;
+  optionsContainerStyle?: CSSProperties;
+
+  // Select button props
+  selectButton?: SelectButtonProps;
+};
+
+export const CustomSelect = ({
+  // Base props
+  label,
+  className,
+  style,
+  id,
+  info,
+  errors,
+  layout = "default",
+
+  // Select options and behavior
+  options,
+  value,
+  defaultValue,
+  onChange,
+  multiple = false,
+  searchable = false,
+  allowCreate = false,
+  showDisplayIcon = true,
+  showDisplayText = true,
+  valueText,
+  disabled = false,
+  readOnly = false,
+  required = false,
+  onClear,
+  placeholder = "Select...",
+  searchPlaceholder = "Search options...",
+
+  // Popover behavior
+  closeOnPathChange = true,
+  closeOnClickOutside = true,
+  animationDuration = 200,
+  position = "bottom",
+  align = "start",
+  autoPosition,
+  collisionPadding,
+
+  // Menu options props
+  optionsContainerClassName,
+  optionsContainerStyle,
+
+  // Nested popover props
+  popover,
+  popoverTrigger,
+  popoverMenu,
+  selectButton,
+}: CustomSelectProps) => {
+  const [searchTerm, setSearchTerm] = useState("");
+  const [isOpen, setIsOpen] = useState(false);
+
+  // Internal state for uncontrolled mode
+  const [internalValue, setInternalValue] = useState<string | string[]>(() => {
+    if (defaultValue !== undefined) {
+      return Array.isArray(defaultValue)
+        ? defaultValue
+        : defaultValue
+          ? [defaultValue]
+          : [];
+    }
+    return multiple ? [] : "";
+  });
+
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+  const isControlled = value !== undefined;
+  const actualValue = isControlled ? value : internalValue;
+  const interactive = !disabled && !readOnly;
+
+  // Normalize to array for consistent handling
+  const selectedValues = useMemo(
+    () =>
+      Array.isArray(actualValue)
+        ? actualValue
+        : actualValue
+          ? [actualValue]
+          : [],
+    [actualValue],
+  );
+
+  // A selected value may not exist in `options` - e.g. when `allowCreate` is
+  // on and the consumer just stores the value without pushing it back into
+  // the options list. Synthesize a "ghost" entry so the trigger displays it,
+  // the menu shows it (multi-select can uncheck), and the "Create" check
+  // doesn't redundantly offer something already selected.
+  const optionsWithSelected = useMemo(() => {
+    if (selectedValues.length === 0) return options;
+    const known = new Set(options.map((option) => option.value));
+    const ghosts = selectedValues
+      .filter((value) => !known.has(value))
+      .map<CustomSelectOption>((value) => ({ value, label: value }));
+    return ghosts.length > 0 ? [...ghosts, ...options] : options;
+  }, [options, selectedValues]);
+
+  // Filter options based on search
+  const filteredOptions = useMemo(
+    () =>
+      searchable && searchTerm
+        ? optionsWithSelected.filter((option) =>
+            [option.label, option.description ?? ""].some((text) =>
+              text.toLowerCase().includes(searchTerm.toLowerCase()),
+            ),
+          )
+        : optionsWithSelected,
+    [optionsWithSelected, searchable, searchTerm],
+  );
+
+  // "Create '<term>'" appears when allowCreate is on and the typed term
+  // doesn't match any existing option (by label or value, case-insensitive).
+  const trimmedTerm = searchTerm.trim();
+  const showCreateOption =
+    allowCreate &&
+    searchable &&
+    trimmedTerm.length > 0 &&
+    !optionsWithSelected.some(
+      (option) =>
+        option.label.toLowerCase() === trimmedTerm.toLowerCase() ||
+        option.value.toLowerCase() === trimmedTerm.toLowerCase(),
+    );
+
+  // Get all selected option data in one place. `optionsWithSelected` is used
+  // for the lookup so ghost entries (selected-but-not-in-options) resolve
+  // back to a displayable label.
+  const selectedOptionData = useMemo(() => {
+    const hasValue = selectedValues.length > 0;
+    const selectedOption = optionsWithSelected.find(
+      (opt) => opt.value === selectedValues[0],
+    );
+    const isMultipleSelection = multiple && selectedValues.length > 1;
+    const singleLabel = selectedOption?.label ?? selectedValues[0];
+
+    return {
+      hasValue,
+      option: selectedOption,
+      label: singleLabel,
+      icon: selectedOption?.icon,
+      displayText: !hasValue
+        ? placeholder
+        : (valueText ??
+          (isMultipleSelection
+            ? `${selectedValues.length} selected`
+            : singleLabel)),
+      shouldShowIcon:
+        showDisplayIcon && selectedOption?.icon && selectedValues.length === 1,
+      appliedClassName: selectedOption?.applyToSelector
+        ? selectedOption.optionClassName
+        : undefined,
+      appliedStyle: selectedOption?.applyToSelector
+        ? selectedOption.optionStyle
+        : undefined,
+    };
+  }, [multiple, optionsWithSelected, placeholder, selectedValues, showDisplayIcon, valueText]);
+
+  const popoverOnClose = popover?.onClose;
+  const handlePopoverClose = useCallback(() => {
+    setSearchTerm("");
+    popoverOnClose?.();
+  }, [popoverOnClose]);
+
+  const {
+    className: popoverClassName,
+    offset: popoverOffset = 4,
+    autoPosition: popoverAutoPosition,
+    collisionPadding: popoverCollisionPadding,
+    ...popoverRest
+  } = popover ?? {};
+  const resolvedAutoPosition = popoverAutoPosition ?? autoPosition;
+  const resolvedCollisionPadding = popoverCollisionPadding ?? collisionPadding;
+
+  const {
+    className: popoverTriggerClassName,
+    style: popoverTriggerStyle,
+    ...popoverTriggerRest
+  } = popoverTrigger ?? {};
+
+  const {
+    className: popoverMenuClassName,
+    style: popoverMenuStyle,
+    ...popoverMenuRest
+  } = popoverMenu ?? {};
+
+  // Handle external value changes for controlled mode
+  useEffect(() => {
+    if (isControlled) {
+      const normalized = Array.isArray(value) ? value : value ? [value] : [];
+      const isDifferent =
+        normalized.length !== selectedValues.length ||
+        normalized.some((val, i) => val !== selectedValues[i]);
+
+      if (isDifferent && !normalized.length) {
+        onClear?.();
+      }
+    }
+  }, [value, onClear, selectedValues, isControlled]);
+
+  const handleSelect = (option: CustomSelectOption) => {
+    if (!interactive || option.disabled) return;
+
+    const optionValue = option.value;
+
+    let newValues: string | string[];
+
+    if (multiple) {
+      newValues = selectedValues.includes(optionValue)
+        ? selectedValues.filter((val) => val !== optionValue)
+        : [...selectedValues, optionValue];
+    } else {
+      newValues = optionValue;
+      setIsOpen(false);
+    }
+
+    if (!isControlled) {
+      setInternalValue(newValues);
+    }
+
+    onChange?.(newValues);
+  };
+
+  // Enter in the search box picks the first row: the Create row while one
+  // shows, else the first option found. A choice already made stays made.
+  const handleSearchKey = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key !== "Enter") return;
+    e.preventDefault();
+    if (!trimmedTerm) return;
+    if (showCreateOption) {
+      handleSelect({ value: trimmedTerm, label: trimmedTerm });
+    } else {
+      const first = filteredOptions.find(
+        (option) =>
+          !option.disabled &&
+          !(multiple && selectedValues.includes(option.value)),
+      );
+      if (first) handleSelect(first);
+    }
+    setSearchTerm("");
+  };
+
+  const handleClear = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (!interactive) return;
+
+    const newValue = multiple ? [] : "";
+
+    if (!isControlled) {
+      setInternalValue(newValue);
+    }
+
+    onChange?.(newValue);
+    onClear?.();
+  };
+
+  return (
+    <div className={clsx(sCommon.container, className)} style={style}>
+      {label && (
+        <div
+          className={clsx(
+            sCommon.field_container,
+            layout !== "default" && sCommon[layout],
+          )}
+        >
+          <label className={sCommon.label} htmlFor={inputId}>
+            {label}
+          </label>
+        </div>
+      )}
+
+      <Popover
+        closeOnPathChange={closeOnPathChange}
+        closeOnClickOutside={closeOnClickOutside}
+        animationDuration={animationDuration}
+        isOpen={isOpen}
+        setIsOpen={setIsOpen}
+        position={position}
+        align={align}
+        autoPosition={resolvedAutoPosition}
+        collisionPadding={resolvedCollisionPadding}
+        className={clsx(sPickerCommon.picker_popover, popoverClassName)}
+        offset={popoverOffset}
+        {...popoverRest}
+        onClose={handlePopoverClose}
+      >
+        <PopoverTrigger
+          asChild
+          className={clsx(
+            sPickerCommon.picker_popover_trigger,
+            popoverTriggerClassName,
+          )}
+          style={popoverTriggerStyle}
+          disabled={disabled || readOnly}
+          {...popoverTriggerRest}
+        >
+          <SelectButton
+            disabled={disabled || readOnly}
+            required={required}
+            showClear={selectedOptionData.hasValue && interactive}
+            onClear={handleClear}
+            id={inputId}
+            className={clsx(
+              !selectedOptionData.hasValue &&
+                sPickerCommon.picker_value_placeholder,
+              selectButton?.className,
+              selectedOptionData.appliedClassName,
+            )}
+            style={{
+              ...selectButton?.style,
+              ...selectedOptionData.appliedStyle,
+            }}
+            iconStart={
+              selectedOptionData.shouldShowIcon ? (
+                <Icon>{selectedOptionData.icon}</Icon>
+              ) : undefined
+            }
+            {...selectButton}
+          >
+            {showDisplayText && (
+              <span className={clsx(s.option_label, sCommon.truncate_text)}>
+                {selectedOptionData.displayText}
+              </span>
+            )}
+          </SelectButton>
+        </PopoverTrigger>
+
+        {!disabled && !readOnly && (
+          <PopoverMenu
+            className={clsx(
+              sPickerCommon.picker_popover_menu_base,
+              s.popover_menu,
+              popoverMenuClassName,
+            )}
+            style={popoverMenuStyle}
+            {...popoverMenuRest}
+          >
+            {searchable && (
+              <div className={s.search_container}>
+                <Input
+                  type="search"
+                  placeholder={searchPlaceholder}
+                  value={searchTerm}
+                  onChange={(e) => setSearchTerm(e.target.value)}
+                  onKeyDown={handleSearchKey}
+                  onClick={(e) => e.stopPropagation()}
+                  showClear={true}
+                  autoFocus
+                />
+              </div>
+            )}
+
+            <div
+              className={clsx(s.options_container, optionsContainerClassName)}
+              style={optionsContainerStyle}
+            >
+              {showCreateOption && (
+                <Button
+                  as="div"
+                  variant="ghost"
+                  className={s.option}
+                  onClick={() => {
+                    handleSelect({ value: trimmedTerm, label: trimmedTerm });
+                    setSearchTerm("");
+                  }}
+                >
+                  <Icon size="sm" aria-hidden="true">
+                    <IconPlus />
+                  </Icon>
+                  <span
+                    className={clsx(s.option_label, sCommon.truncate_text)}
+                  >
+                    Create &ldquo;{trimmedTerm}&rdquo;
+                  </span>
+                </Button>
+              )}
+              {filteredOptions.length === 0 && !showCreateOption ? (
+                <p className={s.no_options}>No options found</p>
+              ) : (
+                filteredOptions.map((option) => (
+                  <Button
+                    key={option.value}
+                    as="div"
+                    variant={option.optionButtonVariant || "ghost"}
+                    className={clsx(
+                      s.option,
+                      option.description && s.option_rich,
+                      option.optionClassName,
+                    )}
+                    style={option.optionStyle}
+                    isActive={selectedValues.includes(option.value)}
+                    disabled={disabled || readOnly || option.disabled}
+                    onClick={() => handleSelect(option)}
+                  >
+                    {multiple && (
+                      <Input
+                        type="checkbox"
+                        className={sCommon.option_checkbox}
+                        checked={selectedValues.includes(option.value)}
+                        disabled={disabled || readOnly || option.disabled}
+                      />
+                    )}
+                    {option.icon && option.icon}
+                    {option.description ? (
+                      <span className={s.option_text}>
+                        <span
+                          className={clsx(
+                            s.option_label,
+                            sCommon.truncate_text,
+                          )}
+                        >
+                          {option.label}
+                        </span>
+                        <span className={s.option_description}>
+                          {option.description}
+                        </span>
+                      </span>
+                    ) : (
+                      <span
+                        className={clsx(s.option_label, sCommon.truncate_text)}
+                      >
+                        {option.label}
+                      </span>
+                    )}
+                    {option.meta != null ? (
+                      <span className={s.option_meta}>{option.meta}</span>
+                    ) : null}
+                    {option.onDelete && interactive ? (
+                      <Icon
+                        size="sm"
+                        clickable
+                        className={s.option_delete}
+                        aria-label={`Delete ${option.label}`}
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          // Close the popover BEFORE handing off - the consumer
+                          // opens a confirm dialog, which must not sit under
+                          // the still-open popover in the stacking order.
+                          setIsOpen(false);
+                          option.onDelete?.();
+                        }}
+                      >
+                        <IconTrash />
+                      </Icon>
+                    ) : null}
+                  </Button>
+                ))
+              )}
+            </div>
+          </PopoverMenu>
+        )}
+      </Popover>
+
+      <FieldMessage errors={errors} info={info} />
+    </div>
+  );
+};