myoperator-mcp 0.2.170 → 0.2.172

package/dist/index.js

@@ -1412,6 +1412,11 @@ export interface CreatableMultiSelectProps
   state?: "default" | "error"
   /** Helper text shown below the trigger */
   helperText?: string
+  /**
+   * Shown inside the open dropdown (e.g. "Type to create a custom tone").
+   * Pair with {@link maxItems} so users see guidance when no preset matches their typing.
+   */
+  createHintText?: string
   /** Max number of items that can be selected (default: unlimited) */
   maxItems?: number
   /** Max character length per item when typing/creating (default: unlimited) */
@@ -1441,6 +1446,7 @@ const CreatableMultiSelect = React.forwardRef(
       disabled = false,
       state = "default",
       helperText,
+      createHintText,
       maxItems,
       maxLengthPerItem,
       sanitizeInput,
@@ -1518,134 +1524,214 @@ const CreatableMultiSelect = React.forwardRef(
           o.label.toLowerCase().includes(inputValue.trim().toLowerCase())
         )
       : availablePresets
+
+    const afterSanitizeDraft = sanitizeInput
+      ? sanitizeInput(inputValue)
+      : inputValue
+    const trimmedDraft = afterSanitizeDraft.trim()
+    const draftForCreate = trimmedDraft
+      ? maxLengthPerItem != null
+        ? trimmedDraft.slice(0, maxLengthPerItem)
+        : trimmedDraft
+      : ""
+
+    const canShowEnterAffordance =
+      Boolean(draftForCreate) &&
+      !value.includes(draftForCreate) &&
+      (maxItems == null || value.length < maxItems)
+
+    const hasHintCopy = Boolean(createHintText) || maxItems != null
+
+    const showHintsRow =
+      hasHintCopy || canShowEnterAffordance
+
     const triggerState = isOpen
       ? state === "error"
         ? "focused-error"
         : "focused"
       : state
 
+    /** Must match \`CreatableSelect\` hint-row \`<kbd>\` (Primary Role) \u2014 includes \`font-sans\` to override UA monospace on \`<kbd>\`. */
+    const creatableHintEnterKbdClassName =
+      "inline-flex items-center gap-0.5 rounded border border-solid border-semantic-border-layout bg-semantic-bg-ui px-1.5 py-0.5 font-sans text-[10px] font-medium text-semantic-text-muted"
+
     return (
       <div
         ref={containerRef}
         className={cn("relative w-full", className)}
         {...props}
       >
-        {/* Trigger */}
-        <div
-          className={cn(
-            creatableMultiSelectTriggerVariants({ state: triggerState }),
-            disabled && "cursor-not-allowed opacity-50"
-          )}
-          onClick={() => {
-            if (disabled) return
-            setIsOpen(true)
-            inputRef.current?.focus()
-          }}
-        >
-          {/* Selected chips */}
-          {value.map((val) => {
-            const optLabel =
-              options.find((o) => o.value === val)?.label || val
-            return (
-              <span
-                key={val}
-                className="inline-flex items-center gap-2 bg-semantic-info-surface px-2 py-1 rounded text-sm text-semantic-text-primary whitespace-nowrap"
-              >
-                {optLabel}
-                <button
-                  type="button"
-                  onMouseDown={(e) => {
-                    e.stopPropagation()
-                    e.preventDefault()
-                    removeValue(val)
-                  }}
-                  className="shrink-0 flex items-center justify-center text-semantic-text-muted hover:text-semantic-text-primary transition-colors"
-                  aria-label={\`Remove \${optLabel}\`}
-                >
-                  <X className="size-2.5" />
-                </button>
-              </span>
-            )
-          })}
-
-          {/* Text input */}
-          <input
-            ref={inputRef}
-            type="text"
-            value={inputValue}
-            onChange={(e) => {
-              const raw = e.target.value
-              const sanitized = sanitizeInput ? sanitizeInput(raw) : raw
-              if (sanitizeInput) {
-                if (raw !== sanitized) onInvalidCharacters?.()
-                else onValidInput?.()
-              }
-              setInputValue(
-                maxLengthPerItem != null
-                  ? sanitized.slice(0, maxLengthPerItem)
-                  : sanitized
-              )
-              if (!isOpen) setIsOpen(true)
-            }}
-            maxLength={maxLengthPerItem}
-            onFocus={() => {
-              if (!disabled) setIsOpen(true)
+        {/* Positioning context = trigger only so the dropdown aligns like CreatableSelect (counter sits below, not above the panel). */}
+        <div className="relative w-full">
+          {/* Trigger */}
+          <div
+            className={cn(
+              creatableMultiSelectTriggerVariants({ state: triggerState }),
+              disabled && "cursor-not-allowed opacity-50"
+            )}
+            onClick={() => {
+              if (disabled) return
+              setIsOpen(true)
+              inputRef.current?.focus()
             }}
-            onKeyDown={handleKeyDown}
-            disabled={disabled}
-            placeholder={value.length === 0 ? placeholder : ""}
-            className="flex-1 min-w-[100px] text-base bg-transparent outline-none text-semantic-text-primary placeholder:text-semantic-text-muted"
-            role="combobox"
-            aria-expanded={isOpen}
-            aria-controls={listboxId}
-            aria-haspopup="listbox"
-          />
-
-          {/* Chevron */}
-          {isOpen ? (
-            <ChevronRight className="size-5 text-semantic-text-muted shrink-0 ml-auto" />
-          ) : (
-            <ChevronDown className="size-5 text-semantic-text-muted shrink-0 ml-auto" />
-          )}
-        </div>
-
-        {/* Dropdown panel */}
-        {isOpen && (
-          <div id={listboxId} role="listbox" className="absolute z-[9999] top-full mt-1 w-full bg-semantic-bg-primary border border-solid border-semantic-border-layout rounded shadow-md animate-in fade-in-0 zoom-in-95 slide-in-from-top-2 duration-200">
-            {/* Preset option chips */}
-            {filteredPresets.length > 0 && (
-              <div className="px-2.5 py-2 flex flex-wrap gap-1.5">
-                {filteredPresets.map((option) => (
+          >
+            {/* Selected chips */}
+            {value.map((val) => {
+              const optLabel =
+                options.find((o) => o.value === val)?.label || val
+              return (
+                <span
+                  key={val}
+                  className="inline-flex items-center gap-2 bg-semantic-info-surface px-2 py-1 rounded text-sm text-semantic-text-primary whitespace-nowrap"
+                >
+                  {optLabel}
                   <button
-                    key={option.value}
                     type="button"
                     onMouseDown={(e) => {
+                      e.stopPropagation()
                       e.preventDefault()
-                      addValue(option.value)
+                      removeValue(val)
                     }}
-                    className="inline-flex items-center gap-1.5 bg-semantic-bg-ui px-2.5 py-1.5 rounded text-sm text-semantic-text-primary hover:bg-semantic-bg-hover transition-colors whitespace-nowrap"
+                    className="shrink-0 flex items-center justify-center text-semantic-text-muted hover:text-semantic-text-primary transition-colors"
+                    aria-label={\`Remove \${optLabel}\`}
                   >
-                    <Plus className="size-3 shrink-0 text-semantic-text-muted" />
-                    {option.label}
+                    <X className="size-2.5" />
                   </button>
-                ))}
-              </div>
-            )}
+                </span>
+              )
+            })}
+
+            {/* Text input */}
+            <input
+              ref={inputRef}
+              type="text"
+              value={inputValue}
+              onChange={(e) => {
+                const raw = e.target.value
+                const sanitized = sanitizeInput ? sanitizeInput(raw) : raw
+                if (sanitizeInput) {
+                  if (raw !== sanitized) onInvalidCharacters?.()
+                  else onValidInput?.()
+                }
+                setInputValue(
+                  maxLengthPerItem != null
+                    ? sanitized.slice(0, maxLengthPerItem)
+                    : sanitized
+                )
+                if (!isOpen) setIsOpen(true)
+              }}
+              maxLength={maxLengthPerItem}
+              onFocus={() => {
+                if (!disabled) setIsOpen(true)
+              }}
+              onKeyDown={handleKeyDown}
+              disabled={disabled}
+              placeholder={value.length === 0 ? placeholder : ""}
+              className="flex-1 min-w-[100px] text-base bg-transparent outline-none text-semantic-text-primary placeholder:text-semantic-text-muted"
+              role="combobox"
+              aria-expanded={isOpen}
+              aria-controls={listboxId}
+              aria-haspopup="listbox"
+            />
 
+            {/* Chevron */}
+            {isOpen ? (
+              <ChevronRight className="size-5 text-semantic-text-muted shrink-0 ml-auto" />
+            ) : (
+              <ChevronDown className="size-5 text-semantic-text-muted shrink-0 ml-auto" />
+            )}
           </div>
-        )}
+
+          {/* Dropdown panel \u2014 top-full is bottom of trigger row only (matches Primary Role / CreatableSelect). */}
+          {isOpen && (
+            <div
+              id={listboxId}
+              role="listbox"
+              className="absolute left-0 top-full z-[9999] mt-1 w-full rounded border border-solid border-semantic-border-layout bg-semantic-bg-primary shadow-md animate-in fade-in-0 zoom-in-95 slide-in-from-top-2 duration-200"
+            >
+              {showHintsRow && (
+                <div
+                  className={cn(
+                    "flex items-center justify-between gap-2 px-4 py-2",
+                    filteredPresets.length > 0 &&
+                      "border-b border-solid border-semantic-border-layout",
+                    !hasHintCopy && "justify-end"
+                  )}
+                >
+                  {hasHintCopy ? (
+                    <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+                      {createHintText ? (
+                        <span className="text-sm text-semantic-text-muted">
+                          {createHintText}
+                        </span>
+                      ) : null}
+                      {maxItems != null ? (
+                        <span className="text-xs text-semantic-text-muted">
+                          Max selections allowed: {maxItems}
+                        </span>
+                      ) : null}
+                    </div>
+                  ) : null}
+                  <span
+                    role="button"
+                    tabIndex={canShowEnterAffordance ? 0 : -1}
+                    aria-label="Add using Enter key"
+                    aria-disabled={!canShowEnterAffordance}
+                    className={cn(
+                      "inline-flex shrink-0",
+                      !canShowEnterAffordance && "pointer-events-none"
+                    )}
+                    onMouseDown={(e) => {
+                      e.preventDefault()
+                      if (canShowEnterAffordance) addValue(inputValue)
+                    }}
+                    onKeyDown={(e) => {
+                      if (e.key !== "Enter" && e.key !== " ") return
+                      e.preventDefault()
+                      if (canShowEnterAffordance) addValue(inputValue)
+                    }}
+                  >
+                    <kbd className={creatableHintEnterKbdClassName}>
+                      Enter \u21B5
+                    </kbd>
+                  </span>
+                </div>
+              )}
+
+              {/* Preset option chips \u2014 pt-1 px-4 matches CreatableSelect listbox padding above first option */}
+              {filteredPresets.length > 0 && (
+                <div className="flex flex-wrap gap-1.5 px-4 pt-1 pb-2">
+                  {filteredPresets.map((option) => (
+                    <button
+                      key={option.value}
+                      type="button"
+                      onMouseDown={(e) => {
+                        e.preventDefault()
+                        addValue(option.value)
+                      }}
+                      className="inline-flex items-center gap-1.5 whitespace-nowrap rounded bg-semantic-bg-ui px-2.5 py-1.5 text-sm text-semantic-text-primary transition-colors hover:bg-semantic-bg-hover"
+                    >
+                      <Plus className="size-3 shrink-0 text-semantic-text-muted" />
+                      {option.label}
+                    </button>
+                  ))}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
 
         {/* Helper row below trigger: when maxLengthPerItem show dynamic hint + counter (Figma); else optional static helperText */}
         {maxLengthPerItem != null ? (
-          <div className="flex items-center justify-end gap-2 mt-1.5">
-            <span className="text-sm text-semantic-text-muted shrink-0">
+          <div className="mt-1.5 flex items-center justify-end gap-2">
+            <span className="shrink-0 text-sm text-semantic-text-muted">
               {inputValue.length}/{maxLengthPerItem}
             </span>
           </div>
         ) : (
           helperText &&
           !isOpen && (
-            <div className="flex items-center gap-1.5 mt-1.5">
+            <div className="mt-1.5 flex items-center gap-1.5">
               <Info className="size-[18px] shrink-0 text-semantic-text-muted" />
               <p className="m-0 text-sm text-semantic-text-muted">
                 {helperText}
@@ -1957,7 +2043,7 @@ const CreatableSelect = React.forwardRef(
                 <span className="text-sm text-semantic-text-muted">
                   {creatableHint}
                 </span>
-                <kbd className="inline-flex items-center gap-0.5 rounded border border-solid border-semantic-border-layout bg-semantic-bg-ui px-1.5 py-0.5 text-[10px] text-semantic-text-muted font-medium">
+                <kbd className="inline-flex items-center gap-0.5 rounded border border-solid border-semantic-border-layout bg-semantic-bg-ui px-1.5 py-0.5 font-sans text-[10px] font-medium text-semantic-text-muted">
                   Enter \u21B5
                 </kbd>
               </div>
@@ -2885,7 +2971,7 @@ const inputVariants = cva(
         default:
           "border border-solid border-semantic-border-input focus:outline-none focus:border-semantic-border-input-focus focus:shadow-[0_0_0_1px_rgba(43,188,202,0.15)]",
         error:
-          "border border-solid border-semantic-error-primary/40 focus:outline-none focus:border-semantic-error-primary focus:shadow-[0_0_0_1px_rgba(240,68,56,0.1)]",
+          "border border-solid border-semantic-error-primary focus:outline-none focus:border-semantic-error-primary focus:shadow-[0_0_0_1px_rgba(240,68,56,0.12)]",
       },
     },
     defaultVariants: {
@@ -2984,9 +3070,114 @@ export { Input, inputVariants };
 `,
   "multi-select": `import * as React from "react";
 import { cva, type VariantProps } from "class-variance-authority";
-import { Check, ChevronDown, X, Loader2 } from "lucide-react";
+import { Check, ChevronDown, CircleAlert, Loader2, X } from "lucide-react";
 
 import { cn } from "@/lib/utils";
+import { Checkbox } from "./checkbox";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "./tooltip";
+
+/**
+ * Single selectable row (similar to legacy OptionType \u2014 different name).
+ * Selection state is driven by \`value\` / \`onValueChange\`, not by a prop.
+ */
+export interface MultiSelectChoice {
+  value: string;
+  label: string;
+  /** Secondary line (e.g. \u201CAssigned to \u2026\u201D) \u2014 alias of \`secondaryText\` on \`MultiSelectOption\` */
+  caption?: string;
+  /** Disabled row \u2014 alias of \`disabled\` */
+  isDisabled?: boolean;
+  /** Tooltip on disabled row \u2014 alias of \`disabledTooltip\` */
+  overlayMsg?: string;
+  isDeleted?: boolean;
+  isLast?: boolean;
+}
+
+/**
+ * Grouped options (similar to legacy GroupBase \u2014 different name).
+ */
+export interface MultiSelectGroupedSection<
+  T extends MultiSelectChoice = MultiSelectChoice,
+> {
+  readonly label?: string;
+  readonly options: readonly T[];
+}
+
+/** Flat list or grouped sections */
+export type MultiSelectOptionInput =
+  | MultiSelectOption[]
+  | readonly MultiSelectGroupedSection[];
+
+/**
+ * Normalized option: supports both \`caption\` / \`isDisabled\` / \`overlayMsg\` and
+ * \`secondaryText\` / \`disabled\` / \`disabledTooltip\`.
+ */
+export interface MultiSelectOption extends MultiSelectChoice {
+  secondaryText?: string;
+  disabled?: boolean;
+  disabledTooltip?: string;
+  group?: string;
+}
+
+/**
+ * Use when typing **object literals** for fixtures, stories, or tests so TypeScript applies
+ * [excess property checking](https://www.typescriptlang.org/docs/handbook/2/objects.html#excess-property-checks)
+ * (catches typos like \`captoin\` and mistaken duplicate keys).
+ *
+ * This omits \`secondaryText\`; use \`caption\` for the secondary line \u2014 runtime code still accepts
+ * both via {@link normalizeMultiSelectOption}. Widen to {@link MultiSelectOption} where a
+ * consumer expects both aliases.
+ */
+export type MultiSelectOptionAuthoring = Omit<MultiSelectOption, "secondaryText">;
+
+function isGroupedSections(
+  input: MultiSelectOptionInput
+): input is readonly MultiSelectGroupedSection[] {
+  if (!Array.isArray(input) || input.length === 0) return false;
+  return input.every(
+    (item) =>
+      item !== null &&
+      typeof item === "object" &&
+      "options" in item &&
+      Array.isArray((item as MultiSelectGroupedSection).options)
+  );
+}
+
+export function normalizeMultiSelectOption(
+  o: MultiSelectOption | MultiSelectChoice
+): MultiSelectOption {
+  const merged = { ...(o as MultiSelectOption) };
+  merged.disabled = merged.disabled ?? merged.isDisabled ?? false;
+  merged.secondaryText = merged.secondaryText ?? merged.caption;
+  merged.disabledTooltip = merged.disabledTooltip ?? merged.overlayMsg;
+  return merged;
+}
+
+export function flattenMultiSelectOptions(
+  input: MultiSelectOptionInput
+): MultiSelectOption[] {
+  if (!input?.length) return [];
+  if (isGroupedSections(input)) {
+    const out: MultiSelectOption[] = [];
+    for (const section of input) {
+      const groupLabel = section.label ?? "";
+      for (const raw of section.options) {
+        const n = normalizeMultiSelectOption(raw as MultiSelectOption);
+        out.push({
+          ...n,
+          group: n.group ?? groupLabel,
+        });
+      }
+    }
+    return out;
+  }
+  return (input as MultiSelectOption[]).map(normalizeMultiSelectOption);
+}
 
 /**
  * MultiSelect trigger variants matching TextField styling
@@ -3008,15 +3199,6 @@ const multiSelectTriggerVariants = cva(
   }
 );
 
-export interface MultiSelectOption {
-  /** The value of the option */
-  value: string;
-  /** The display label of the option */
-  label: string;
-  /** Whether the option is disabled */
-  disabled?: boolean;
-}
-
 export interface MultiSelectProps extends VariantProps<
   typeof multiSelectTriggerVariants
 > {
@@ -3040,14 +3222,25 @@ export interface MultiSelectProps extends VariantProps<
   defaultValue?: string[];
   /** Callback when values change */
   onValueChange?: (value: string[]) => void;
-  /** Options to display */
-  options: MultiSelectOption[];
+  /** Flat options or grouped sections (\`MultiSelectGroupedSection[]\`) */
+  options: MultiSelectOptionInput;
+  /**
+   * When false (default), the list only closes on outside click (not Escape).
+   * Set true to also close on Escape.
+   */
+  closeOnEscape?: boolean;
   /** Enable search/filter functionality */
   searchable?: boolean;
   /** Search placeholder text */
   searchPlaceholder?: string;
   /** Maximum selections allowed */
   maxSelections?: number;
+  /**
+   * When \`maxSelections\` is set, a footer shows the count (e.g. "3 / 5 selected").
+   * Set to false to hide that footer while still enforcing the limit.
+   * @default true
+   */
+  showSelectionFooter?: boolean;
   /** Additional class for wrapper */
   wrapperClassName?: string;
   /** Additional class for trigger */
@@ -3058,6 +3251,17 @@ export interface MultiSelectProps extends VariantProps<
   id?: string;
   /** Name attribute for form submission */
   name?: string;
+  /**
+   * simple: checkmark on the right (default).
+   * detailed: checkbox + primary + optional secondary text (Figma / WhatsApp-style rows).
+   */
+  optionVariant?: "simple" | "detailed";
+  /** When true, selected options appear first with a divider before the rest */
+  separateSelectedWithDivider?: boolean;
+  /** Show the clear-all control in the trigger (hidden in compact / Figma-style triggers) */
+  showClearAll?: boolean;
+  /** Vertical rule before the chevron (Figma-style trigger) */
+  showSeparatorBeforeChevron?: boolean;
 }
 
 /**
@@ -3094,12 +3298,18 @@ const MultiSelect = React.forwardRef(
       searchable,
       searchPlaceholder = "Search...",
       maxSelections,
+      showSelectionFooter = true,
       wrapperClassName,
       triggerClassName,
       labelClassName,
       state,
       id,
       name,
+      optionVariant = "simple",
+      separateSelectedWithDivider = false,
+      showClearAll = true,
+      showSeparatorBeforeChevron = false,
+      closeOnEscape = false,
     }: MultiSelectProps,
     ref: React.Ref<HTMLButtonElement>
   ) => {
@@ -3114,6 +3324,11 @@ const MultiSelect = React.forwardRef(
     // Container ref for click outside detection
     const containerRef = React.useRef<HTMLDivElement>(null);
 
+    const flatOptions = React.useMemo(
+      () => flattenMultiSelectOptions(options),
+      [options]
+    );
+
     // Determine if controlled
     const isControlled = value !== undefined;
     const selectedValues = isControlled ? value : internalValue;
@@ -3133,18 +3348,87 @@ const MultiSelect = React.forwardRef(
 
     // Filter options by search query
     const filteredOptions = React.useMemo(() => {
-      if (!searchable || !searchQuery) return options;
-      return options.filter((option) =>
-        option.label.toLowerCase().includes(searchQuery.toLowerCase())
-      );
-    }, [options, searchable, searchQuery]);
+      if (!searchable || !searchQuery.trim()) return flatOptions;
+      const q = searchQuery.toLowerCase();
+      return flatOptions.filter((option) => {
+        const secondary = option.secondaryText ?? "";
+        return (
+          option.label.toLowerCase().includes(q) ||
+          secondary.toLowerCase().includes(q) ||
+          (option.group?.toLowerCase().includes(q) ?? false)
+        );
+      });
+    }, [flatOptions, searchable, searchQuery]);
+
+    type DisplayItem =
+      | { type: "option"; option: MultiSelectOption }
+      | { type: "divider" }
+      | { type: "header"; label: string };
+
+    const hasGroupedOptions = flatOptions.some(
+      (o) => o.group !== undefined && o.group !== ""
+    );
+
+    const displayItems = React.useMemo((): DisplayItem[] => {
+      const filtered = filteredOptions;
+
+      if (separateSelectedWithDivider) {
+        const selected = filtered.filter((o) =>
+          selectedValues.includes(o.value)
+        );
+        const unselected = filtered.filter(
+          (o) => !selectedValues.includes(o.value)
+        );
+        const items: DisplayItem[] = selected.map((o) => ({
+          type: "option",
+          option: o,
+        }));
+        if (selected.length > 0 && unselected.length > 0) {
+          items.push({ type: "divider" });
+        }
+        items.push(
+          ...unselected.map((o) => ({ type: "option" as const, option: o }))
+        );
+        return items;
+      }
+
+      if (hasGroupedOptions) {
+        const order: string[] = [];
+        const byGroup = new Map<string, MultiSelectOption[]>();
+        for (const o of filtered) {
+          const g = o.group ?? "";
+          if (!byGroup.has(g)) {
+            byGroup.set(g, []);
+            order.push(g);
+          }
+          byGroup.get(g)!.push(o);
+        }
+        const items: DisplayItem[] = [];
+        for (const g of order) {
+          if (g) {
+            items.push({ type: "header", label: g });
+          }
+          for (const o of byGroup.get(g)!) {
+            items.push({ type: "option", option: o });
+          }
+        }
+        return items;
+      }
+
+      return filtered.map((o) => ({ type: "option" as const, option: o }));
+    }, [
+      filteredOptions,
+      hasGroupedOptions,
+      separateSelectedWithDivider,
+      selectedValues,
+    ]);
 
     // Get selected option labels
     const selectedLabels = React.useMemo(() => {
       return selectedValues
-        .map((v) => options.find((o) => o.value === v)?.label)
+        .map((v) => flatOptions.find((o) => o.value === v)?.label)
         .filter(Boolean) as string[];
-    }, [selectedValues, options]);
+    }, [selectedValues, flatOptions]);
 
     // Handle toggle selection
     const toggleOption = (optionValue: string) => {
@@ -3198,7 +3482,7 @@ const MultiSelect = React.forwardRef(
 
     // Handle keyboard navigation
     const handleKeyDown = (e: React.KeyboardEvent) => {
-      if (e.key === "Escape") {
+      if (e.key === "Escape" && closeOnEscape) {
         setIsOpen(false);
         setSearchQuery("");
       } else if (e.key === "Enter" || e.key === " ") {
@@ -3212,7 +3496,7 @@ const MultiSelect = React.forwardRef(
     return (
       <div
         ref={containerRef}
-        className={cn("flex flex-col gap-1 relative", wrapperClassName)}
+        className={cn("flex flex-col gap-1", wrapperClassName)}
       >
         {/* Label */}
         {label && (
@@ -3230,26 +3514,29 @@ const MultiSelect = React.forwardRef(
           </label>
         )}
 
-        {/* Trigger */}
-        <button
-          ref={ref}
-          id={selectId}
-          type="button"
-          role="combobox"
-          aria-expanded={isOpen}
-          aria-haspopup="listbox"
-          aria-controls={listboxId}
-          aria-invalid={!!error}
-          aria-describedby={ariaDescribedBy}
-          disabled={disabled || loading}
-          onClick={() => !disabled && !loading && setIsOpen(!isOpen)}
-          onKeyDown={handleKeyDown}
-          className={cn(
-            multiSelectTriggerVariants({ state: derivedState }),
-            "text-left gap-2",
-            triggerClassName
-          )}
-        >
+        {/* Trigger + helper/error + listbox share one positioning context so the
+            menu opens directly under the field (and under helper text when present). */}
+        <div className="relative w-full min-w-0 flex flex-col gap-1">
+          {/* Trigger */}
+          <button
+            ref={ref}
+            id={selectId}
+            type="button"
+            role="combobox"
+            aria-expanded={isOpen}
+            aria-haspopup="listbox"
+            aria-controls={listboxId}
+            aria-invalid={!!error}
+            aria-describedby={ariaDescribedBy}
+            disabled={disabled || loading}
+            onClick={() => !disabled && !loading && setIsOpen(!isOpen)}
+            onKeyDown={handleKeyDown}
+            className={cn(
+              multiSelectTriggerVariants({ state: derivedState }),
+              "text-left gap-2",
+              triggerClassName
+            )}
+          >
           <div className="flex-1 flex flex-wrap gap-1">
             {selectedValues.length === 0 ? (
               <span className="text-semantic-text-placeholder">
@@ -3284,8 +3571,8 @@ const MultiSelect = React.forwardRef(
               ))
             )}
           </div>
-          <div className="flex items-center gap-1">
-            {selectedValues.length > 0 && (
+          <div className="flex items-center gap-2 shrink-0">
+            {showClearAll && selectedValues.length > 0 && (
               <span
                 role="button"
                 tabIndex={0}
@@ -3302,12 +3589,18 @@ const MultiSelect = React.forwardRef(
                 <X className="size-4 text-semantic-text-muted" />
               </span>
             )}
+            {showSeparatorBeforeChevron && (
+              <div
+                className="w-px h-5 self-center border-l border-solid border-semantic-border-layout shrink-0"
+                aria-hidden
+              />
+            )}
             {loading ? (
               <Loader2 className="size-4 animate-spin text-semantic-text-muted" />
             ) : (
               <ChevronDown
                 className={cn(
-                  "size-4 text-semantic-text-muted transition-transform",
+                  "size-4 text-semantic-text-muted transition-transform shrink-0",
                   isOpen && "rotate-180"
                 )}
               />
@@ -3315,106 +3608,216 @@ const MultiSelect = React.forwardRef(
           </div>
         </button>
 
-        {/* Dropdown */}
-        {isOpen && (
-          <div
-            id={listboxId}
-            className={cn(
-              "absolute z-50 mt-1 w-full rounded bg-semantic-bg-primary border border-solid border-semantic-border-layout shadow-md",
-              "top-full"
-            )}
-            role="listbox"
-            aria-multiselectable="true"
-          >
-            {/* Search input */}
-            {searchable && (
-              <div className="p-2 border-b border-solid border-semantic-border-layout">
-                <input
-                  type="text"
-                  placeholder={searchPlaceholder}
-                  value={searchQuery}
-                  onChange={(e) => setSearchQuery(e.target.value)}
-                  className="w-full h-8 px-3 text-sm border border-solid border-semantic-border-input rounded bg-semantic-bg-primary placeholder:text-semantic-text-placeholder focus:outline-none focus:border-semantic-border-input-focus/50"
-                  onClick={(e) => e.stopPropagation()}
-                />
-              </div>
-            )}
+          {/* Helper / error sits between trigger and dropdown (normal flow), matching Figma */}
+          {(error || helperText) && (
+            <div className="flex justify-between items-start gap-2">
+              {error ? (
+                <div
+                  id={errorId}
+                  role="alert"
+                  className="flex items-center gap-1.5 min-w-0"
+                >
+                  <CircleAlert
+                    className="size-3.5 shrink-0 text-semantic-error-primary"
+                    aria-hidden
+                  />
+                  <span className="text-xs text-semantic-error-primary">
+                    {error}
+                  </span>
+                </div>
+              ) : helperText ? (
+                <span
+                  id={helperId}
+                  className="text-xs text-semantic-text-muted"
+                >
+                  {helperText}
+                </span>
+              ) : null}
+            </div>
+          )}
 
-            {/* Options */}
-            <div className="max-h-60 overflow-auto p-1">
-              {filteredOptions.length === 0 ? (
-                <div className="py-6 text-center text-sm text-semantic-text-muted">
-                  No results found
+          {/* Dropdown */}
+          {isOpen && (
+            <TooltipProvider delayDuration={200}>
+              <div
+                id={listboxId}
+                className={cn(
+                  "absolute left-0 right-0 z-[100] mt-1 w-full rounded bg-semantic-bg-primary border border-solid border-semantic-border-layout shadow-md",
+                  "top-full"
+                )}
+                role="listbox"
+                aria-multiselectable="true"
+              >
+              {/* Search input */}
+              {searchable && (
+                <div className="p-2 border-b border-solid border-semantic-border-layout">
+                  <input
+                    type="text"
+                    placeholder={searchPlaceholder}
+                    value={searchQuery}
+                    onChange={(e) => setSearchQuery(e.target.value)}
+                    className="w-full h-8 px-3 text-sm border border-solid border-semantic-border-input rounded bg-semantic-bg-primary placeholder:text-semantic-text-placeholder focus:outline-none focus:border-semantic-border-input-focus/50"
+                    onClick={(e) => e.stopPropagation()}
+                  />
                 </div>
-              ) : (
-                filteredOptions.map((option) => {
-                  const isSelected = selectedValues.includes(option.value);
-                  const isDisabled =
-                    option.disabled ||
-                    (!isSelected &&
+              )}
+
+              {/* Options */}
+              <div className="max-h-60 overflow-auto p-1">
+                {filteredOptions.length === 0 ? (
+                  <div className="py-6 text-center text-sm text-semantic-text-muted">
+                    No results found
+                  </div>
+                ) : (
+                  displayItems.map((item, itemIndex) => {
+                    if (item.type === "divider") {
+                      return (
+                        <div
+                          key={\`divider-\${itemIndex}\`}
+                          role="separator"
+                          className="my-1 h-px bg-semantic-border-layout"
+                        />
+                      );
+                    }
+                    if (item.type === "header") {
+                      return (
+                        <div
+                          key={\`header-\${item.label}-\${itemIndex}\`}
+                          className="px-3 pt-2 pb-1 text-xs font-semibold uppercase tracking-wide text-semantic-text-muted"
+                        >
+                          {item.label}
+                        </div>
+                      );
+                    }
+
+                    const option = item.option;
+                    const isSelected = selectedValues.includes(option.value);
+                    const isMaxedOut =
+                      !isSelected &&
                       maxSelections !== undefined &&
                       maxSelections > 0 &&
-                      selectedValues.length >= maxSelections);
-
-                  return (
-                    <button
-                      key={option.value}
-                      type="button"
-                      role="option"
-                      aria-selected={isSelected}
-                      disabled={isDisabled}
-                      onClick={() => !isDisabled && toggleOption(option.value)}
-                      className={cn(
-                        "relative flex w-full cursor-pointer select-none items-center rounded-sm py-2 pl-4 pr-8 text-base text-semantic-text-primary outline-none",
+                      selectedValues.length >= maxSelections;
+                    const isDisabled =
+                      Boolean(option.disabled) || isMaxedOut;
+                    const secondaryLine = option.secondaryText ?? option.caption;
+
+                    const rowClass = cn(
+                      "relative flex w-full cursor-pointer select-none items-center rounded-sm text-left text-semantic-text-primary outline-none",
+                      optionVariant === "detailed"
+                        ? "gap-2 px-2 py-2 text-sm"
+                        : "py-2 pl-4 pr-8 text-base",
+                      !isSelected &&
                         "hover:bg-semantic-bg-ui focus:bg-semantic-bg-ui",
-                        isSelected && "bg-semantic-bg-ui",
-                        isDisabled && "pointer-events-none opacity-50"
-                      )}
-                    >
-                      <span className="absolute right-2 flex size-4 items-center justify-center">
-                        {isSelected && (
-                          <Check className="size-4 text-semantic-brand" />
-                        )}
-                      </span>
-                      {option.label}
-                    </button>
-                  );
-                })
-              )}
-            </div>
+                      isDisabled && "opacity-50 cursor-not-allowed",
+                      option.isDeleted && "line-through opacity-70"
+                    );
+
+                    const simpleRow = (
+                      <button
+                        type="button"
+                        role="option"
+                        aria-selected={isSelected}
+                        disabled={isDisabled}
+                        onClick={() =>
+                          !isDisabled && toggleOption(option.value)
+                        }
+                        className={rowClass}
+                      >
+                        <span className="absolute right-2 flex size-4 items-center justify-center">
+                          {isSelected && (
+                            <Check className="size-4 text-semantic-brand" />
+                          )}
+                        </span>
+                        {option.label}
+                      </button>
+                    );
+
+                    const detailedRow = (
+                      <div
+                        role="option"
+                        tabIndex={isDisabled ? -1 : 0}
+                        aria-selected={isSelected}
+                        aria-disabled={isDisabled}
+                        data-disabled={isDisabled ? "" : undefined}
+                        onClick={() =>
+                          !isDisabled && toggleOption(option.value)
+                        }
+                        onKeyDown={(e) => {
+                          if (e.key === "Enter" || e.key === " ") {
+                            e.preventDefault();
+                            if (!isDisabled) toggleOption(option.value);
+                          }
+                        }}
+                        className={rowClass}
+                      >
+                        <Checkbox
+                          checked={isSelected}
+                          disabled={isDisabled}
+                          size="sm"
+                          className="pointer-events-none shrink-0"
+                          aria-hidden
+                          tabIndex={-1}
+                        />
+                        <span className="min-w-0 flex-1 truncate text-left">
+                          {option.label}
+                        </span>
+                        {secondaryLine ? (
+                          <span className="shrink-0 max-w-[55%] truncate text-right text-xs text-semantic-text-muted">
+                            {secondaryLine}
+                          </span>
+                        ) : null}
+                      </div>
+                    );
+
+                    const overlayCopy =
+                      option.disabledTooltip ?? option.overlayMsg;
+
+                    const withDisabledTooltip = (node: React.ReactElement) =>
+                      isDisabled && overlayCopy ? (
+                        <Tooltip key={option.value}>
+                          <TooltipTrigger asChild>
+                            <span className="block w-full cursor-default">
+                              {node}
+                            </span>
+                          </TooltipTrigger>
+                          <TooltipContent
+                            side="top"
+                            className="max-w-xs bg-semantic-primary text-semantic-text-inverted border-semantic-primary"
+                          >
+                            {overlayCopy}
+                          </TooltipContent>
+                        </Tooltip>
+                      ) : (
+                        <React.Fragment key={option.value}>
+                          {node}
+                        </React.Fragment>
+                      );
+
+                    if (optionVariant === "detailed") {
+                      return withDisabledTooltip(detailedRow);
+                    }
+
+                    return withDisabledTooltip(simpleRow);
+                  })
+                )}
+              </div>
 
-            {/* Footer with count */}
-            {maxSelections && (
-              <div className="p-2 border-t border-solid border-semantic-border-layout text-xs text-semantic-text-muted">
-                {selectedValues.length} / {maxSelections} selected
+              {/* Footer with count */}
+              {maxSelections && showSelectionFooter ? (
+                <div className="p-2 border-t border-solid border-semantic-border-layout text-xs text-semantic-text-muted">
+                  {selectedValues.length} / {maxSelections} selected
+                </div>
+              ) : null}
               </div>
-            )}
-          </div>
-        )}
+            </TooltipProvider>
+          )}
+        </div>
 
         {/* Hidden input for form submission */}
         {name &&
           selectedValues.map((v) => (
             <input key={v} type="hidden" name={name} value={v} />
           ))}
-
-        {/* Helper text / Error message */}
-        {(error || helperText) && (
-          <div className="flex justify-between items-start gap-2">
-            {error ? (
-              <span
-                id={errorId}
-                className="text-xs text-semantic-error-primary"
-              >
-                {error}
-              </span>
-            ) : helperText ? (
-              <span id={helperId} className="text-xs text-semantic-text-muted">
-                {helperText}
-              </span>
-            ) : null}
-          </div>
-        )}
       </div>
     );
   }
@@ -3493,6 +3896,8 @@ const NumberStepField = React.forwardRef<HTMLDivElement, NumberStepFieldProps>(
     },
     ref
   ) => {
+    const inputRef = React.useRef<HTMLInputElement>(null);
+
     const handleChange = (raw: string) => {
       const parsed = parseOptionalInt(raw);
       if (parsed === null) return;
@@ -3507,6 +3912,13 @@ const NumberStepField = React.forwardRef<HTMLDivElement, NumberStepFieldProps>(
       onValueChange(clampInt(value - step, min, max));
     };
 
+    /** Keeps focus on the input (not the button) so stepping after typing does not drop focus; also focuses the field when only the steppers are used so blur handlers run on leave. */
+    const handleStepperPointerDown = (e: React.PointerEvent) => {
+      if (disabled) return;
+      e.preventDefault();
+      inputRef.current?.focus();
+    };
+
     const atMax = value >= max;
     const atMin = value <= min;
 
@@ -3516,8 +3928,9 @@ const NumberStepField = React.forwardRef<HTMLDivElement, NumberStepFieldProps>(
         className={cn(numberStepFieldVariants({ layout: "default" }), className)}
         {...props}
       >
-        <div className="flex min-w-0 flex-1 items-stretch rounded-md border border-solid border-semantic-border-input overflow-hidden focus-within:border-semantic-border-input-focus focus-within:shadow-[0_0_0_1px_rgba(43,188,202,0.15)]">
+        <div className="flex min-w-0 flex-1 items-center rounded-md border border-solid border-semantic-border-input overflow-hidden focus-within:border-semantic-border-input-focus focus-within:shadow-[0_0_0_1px_rgba(43,188,202,0.15)]">
           <Input
+            ref={inputRef}
             type="number"
             min={min}
             max={max}
@@ -3530,29 +3943,31 @@ const NumberStepField = React.forwardRef<HTMLDivElement, NumberStepFieldProps>(
             hideNumberSpinners
             className="rounded-none border-0 h-10 min-w-0 flex-1 bg-semantic-bg-primary px-3 py-2 focus-visible:ring-0 focus-visible:ring-offset-0 shadow-none"
           />
-          {/* Inline steppers on the right inside the white field (before unit suffix) */}
-          <div className="flex h-10 w-7 shrink-0 flex-col bg-semantic-bg-primary pr-0.5">
+          {/* Steppers \u2014 markup matches Advanced Settings \`ValidatedNumberSpinner\` (advanced-settings-card.tsx) */}
+          <div className="flex flex-col items-center shrink-0 gap-0.5 bg-semantic-bg-primary pl-0.5 pr-1.5">
             <button
               type="button"
               disabled={disabled || atMax}
+              onPointerDown={handleStepperPointerDown}
               onClick={stepUp}
               aria-label={incrementAriaLabel ?? "Increase value"}
-              className="flex min-h-0 flex-1 items-center justify-center text-semantic-text-muted hover:bg-semantic-bg-hover hover:text-semantic-text-primary disabled:pointer-events-none disabled:opacity-40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-semantic-primary"
+              className="flex items-center justify-center text-semantic-text-muted hover:text-semantic-text-primary transition-colors disabled:cursor-not-allowed disabled:opacity-40"
             >
-              <ChevronUp className="size-3.5" strokeWidth={2} />
+              <ChevronUp className="size-3" />
             </button>
             <button
               type="button"
               disabled={disabled || atMin}
+              onPointerDown={handleStepperPointerDown}
               onClick={stepDown}
               aria-label={decrementAriaLabel ?? "Decrease value"}
-              className="flex min-h-0 flex-1 items-center justify-center text-semantic-text-muted hover:bg-semantic-bg-hover hover:text-semantic-text-primary disabled:pointer-events-none disabled:opacity-40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-semantic-primary"
+              className="flex items-center justify-center text-semantic-text-muted hover:text-semantic-text-primary transition-colors disabled:cursor-not-allowed disabled:opacity-40"
             >
-              <ChevronDown className="size-3.5" strokeWidth={2} />
+              <ChevronDown className="size-3" />
             </button>
           </div>
           <span
-            className="inline-flex items-center px-2.5 shrink-0 bg-semantic-bg-ui text-sm text-semantic-text-secondary"
+            className="inline-flex h-10 items-center pl-3 pr-3.5 shrink-0 bg-semantic-bg-ui text-sm text-semantic-text-secondary"
             aria-hidden
           >
             {suffix}
@@ -5146,42 +5561,65 @@ function useUnlockBodyScroll() {
   }, []);
 }
 
-const SelectContent = React.forwardRef(({ className, children, position = "popper", ...props }: React.ComponentPropsWithoutRef<typeof SelectPrimitive.Content>, ref: React.Ref<React.ElementRef<typeof SelectPrimitive.Content>>) => {
-  useUnlockBodyScroll();
+export type SelectContentProps = React.ComponentPropsWithoutRef<
+  typeof SelectPrimitive.Content
+> & {
+  /**
+   * Fires on the scrollable list viewport when scrolling completes (\`scrollend\`).
+   * Use with paginated option lists (e.g. load the next page when the user reaches the bottom).
+   */
+  onViewportScrollEnd?: (event: React.UIEvent<HTMLDivElement>) => void;
+};
 
-  return (
-    <SelectPrimitive.Portal>
-      <SelectPrimitive.Content
-        ref={ref}
-        className={cn(
-          "relative z-[9999] max-h-96 min-w-[8rem] overflow-hidden rounded bg-semantic-bg-primary border border-solid border-semantic-border-layout shadow-md",
-          "data-[state=open]:animate-in data-[state=closed]:animate-out",
-          "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
-          "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
-          "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2",
-          "data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
-          position === "popper" &&
-            "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
-          className
-        )}
-        position={position}
-        {...props}
-      >
-        <SelectScrollUpButton />
-        <SelectPrimitive.Viewport
+const SelectContent = React.forwardRef(
+  (
+    {
+      className,
+      children,
+      position = "popper",
+      onViewportScrollEnd,
+      ...props
+    }: SelectContentProps,
+    ref: React.Ref<React.ElementRef<typeof SelectPrimitive.Content>>
+  ) => {
+    useUnlockBodyScroll();
+
+    return (
+      <SelectPrimitive.Portal>
+        <SelectPrimitive.Content
+          ref={ref}
           className={cn(
-            "p-1",
+            "relative z-[9999] max-h-96 min-w-[8rem] overflow-hidden rounded bg-semantic-bg-primary border border-solid border-semantic-border-layout shadow-md",
+            "data-[state=open]:animate-in data-[state=closed]:animate-out",
+            "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+            "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+            "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2",
+            "data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
             position === "popper" &&
-              "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)]"
+              "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
+            className
           )}
+          position={position}
+          {...props}
         >
-          {children}
-        </SelectPrimitive.Viewport>
-        <SelectScrollDownButton />
-      </SelectPrimitive.Content>
-    </SelectPrimitive.Portal>
-  );
-});
+          <SelectScrollUpButton />
+          <SelectPrimitive.Viewport
+            data-select-viewport=""
+            className={cn(
+              "p-1",
+              position === "popper" &&
+                "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)]"
+            )}
+            onScrollEnd={onViewportScrollEnd}
+          >
+            {children}
+          </SelectPrimitive.Viewport>
+          <SelectScrollDownButton />
+        </SelectPrimitive.Content>
+      </SelectPrimitive.Portal>
+    );
+  }
+);
 SelectContent.displayName = SelectPrimitive.Content.displayName;
 
 const SelectLabel = React.forwardRef(({ className, ...props }: React.ComponentPropsWithoutRef<typeof SelectPrimitive.Label>, ref: React.Ref<React.ElementRef<typeof SelectPrimitive.Label>>) => (
@@ -6520,6 +6958,7 @@ TextField.displayName = "TextField";
 export { TextField, textFieldContainerVariants, textFieldInputVariants };
 `,
   "textarea": `import * as React from "react";
+import { CircleAlert } from "lucide-react";
 import { cva, type VariantProps } from "class-variance-authority";
 
 import { cn } from "@/lib/utils";
@@ -6535,7 +6974,7 @@ const textareaVariants = cva(
         default:
           "border border-solid border-semantic-border-input focus:outline-none focus:border-semantic-border-input-focus focus:shadow-[0_0_0_1px_rgba(43,188,202,0.15)]",
         error:
-          "border border-solid border-semantic-error-primary/40 focus:outline-none focus:border-semantic-error-primary focus:shadow-[0_0_0_1px_rgba(240,68,56,0.1)]",
+          "border border-solid border-semantic-error-primary focus:outline-none focus:border-semantic-error-primary focus:shadow-[0_0_0_1px_rgba(240,68,56,0.12)]",
       },
       size: {
         default: "px-4 py-2.5 text-base",
@@ -6556,6 +6995,8 @@ const textareaVariants = cva(
  * \`\`\`tsx
  * <Textarea label="Description" placeholder="Enter description" />
  * <Textarea label="Notes" error="Too short" showCount maxLength={500} />
+ * <Textarea label="Notes" showCount maxLength={5000} enforceMaxLength={false} error={overflowMsg} />
+ * <Textarea label="Message" error="Invalid characters not allowed." errorIcon />
  * <Textarea label="JSON" rows={8} resize="vertical" />
  * \`\`\`
  */
@@ -6572,8 +7013,17 @@ export interface TextareaProps
   helperText?: string;
   /** Error message \u2014 shows error state with red styling */
   error?: string;
+  /**
+   * When true and \`error\` is set, shows a leading error icon with the message (field-level validation pattern).
+   */
+  errorIcon?: boolean;
   /** Shows character count when maxLength is set */
   showCount?: boolean;
+  /**
+   * When true (default), \`maxLength\` is applied to the native textarea (hard limit).
+   * When false, the limit is only used for \`showCount\` / styling \u2014 pair with \`error\` or parent validation for soft limits.
+   */
+  enforceMaxLength?: boolean;
   /** Controls CSS resize behavior. Defaults to "none" */
   resize?: "none" | "vertical" | "horizontal" | "both";
   /** Additional class for the wrapper container */
@@ -6594,7 +7044,9 @@ const Textarea = React.forwardRef(
       required,
       helperText,
       error,
+      errorIcon = false,
       showCount,
+      enforceMaxLength = true,
       resize = "none",
       maxLength,
       rows = 4,
@@ -6675,7 +7127,10 @@ const Textarea = React.forwardRef(
             resizeClasses[resize]
           )}
           disabled={disabled}
-          maxLength={maxLength}
+          required={required}
+          maxLength={
+            enforceMaxLength !== false ? maxLength : undefined
+          }
           value={isControlled ? value : undefined}
           defaultValue={!isControlled ? defaultValue : undefined}
           onChange={handleChange}
@@ -6688,12 +7143,28 @@ const Textarea = React.forwardRef(
         {(error || helperText || (showCount && maxLength)) && (
           <div className="flex justify-between items-start gap-2">
             {error ? (
-              <span
-                id={errorId}
-                className="text-sm text-semantic-error-primary"
-              >
-                {error}
-              </span>
+              errorIcon ? (
+                <div
+                  id={errorId}
+                  role="alert"
+                  className="flex items-center gap-1.5 min-w-0"
+                >
+                  <CircleAlert
+                    className="size-3.5 shrink-0 text-semantic-error-primary"
+                    aria-hidden
+                  />
+                  <span className="text-sm text-semantic-error-primary">
+                    {error}
+                  </span>
+                </div>
+              ) : (
+                <span
+                  id={errorId}
+                  className="text-sm text-semantic-error-primary"
+                >
+                  {error}
+                </span>
+              )
             ) : helperText ? (
               <span id={helperId} className="text-sm text-semantic-text-muted">
                 {helperText}
@@ -7199,9 +7670,177 @@ import { cn } from "@/lib/utils";
 
 const TooltipProvider = TooltipPrimitive.Provider;
 
-const Tooltip = TooltipPrimitive.Root;
+/** True when the primary input cannot hover (touch / most phones & tablets). Desktop hover stays false. */
+function usePrefersTapTooltipInteraction() {
+  const [tapMode, setTapMode] = React.useState(() => {
+    if (typeof window === "undefined" || !window.matchMedia) {
+      return false;
+    }
+    return window.matchMedia("(hover: none)").matches;
+  });
 
-const TooltipTrigger = TooltipPrimitive.Trigger;
+  React.useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) {
+      return;
+    }
+    const mq = window.matchMedia("(hover: none)");
+    const sync = () => setTapMode(mq.matches);
+    sync();
+    mq.addEventListener("change", sync);
+    return () => mq.removeEventListener("change", sync);
+  }, []);
+
+  return tapMode;
+}
+
+type TooltipFieldContextValue = {
+  tapMode: boolean;
+  open: boolean;
+  setOpen: (next: boolean | ((prev: boolean) => boolean)) => void;
+  isControlled: boolean;
+  /** True after pointerdown on touch; Radix may fire onOpenChange(true) from focus before click \u2014 ignore that open. */
+  suppressFocusOpenRef: React.MutableRefObject<boolean>;
+};
+
+const TooltipFieldContext = React.createContext<TooltipFieldContextValue | null>(null);
+
+function useTooltipFieldContext() {
+  const ctx = React.useContext(TooltipFieldContext);
+  if (!ctx) {
+    throw new Error("TooltipTrigger must be used within Tooltip");
+  }
+  return ctx;
+}
+
+function composeEventHandlers<E extends React.SyntheticEvent>(
+  original: React.EventHandler<E> | undefined,
+  next: React.EventHandler<E> | undefined,
+) {
+  return (event: E) => {
+    original?.(event);
+    if (!event.defaultPrevented) {
+      next?.(event);
+    }
+  };
+}
+
+const Tooltip = (props: React.ComponentProps<typeof TooltipPrimitive.Root>) => {
+  const { open: openProp, defaultOpen, onOpenChange: onOpenChangeProp, delayDuration: delayDurationProp } = props;
+  const tapMode = usePrefersTapTooltipInteraction();
+  const isControlled = openProp !== undefined;
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(() => defaultOpen ?? false);
+
+  const suppressFocusOpenRef = React.useRef(false);
+
+  const handleOpenChange = React.useCallback(
+    (next: boolean) => {
+      if (!isControlled) {
+        if (tapMode && next === true && suppressFocusOpenRef.current) {
+          return;
+        }
+        setUncontrolledOpen(next);
+      }
+      onOpenChangeProp?.(next);
+    },
+    [isControlled, onOpenChangeProp, tapMode],
+  );
+
+  const openSnapshot = isControlled ? openProp! : uncontrolledOpen;
+
+  const setOpen = React.useCallback(
+    (next: boolean | ((prev: boolean) => boolean)) => {
+      if (isControlled) {
+        const value = typeof next === "function" ? next(openProp!) : next;
+        onOpenChangeProp?.(value);
+      } else {
+        setUncontrolledOpen(next);
+      }
+    },
+    [isControlled, openProp, onOpenChangeProp],
+  );
+
+  const rootProps: React.ComponentProps<typeof TooltipPrimitive.Root> = (() => {
+    if (isControlled) {
+      return props;
+    }
+    if (tapMode) {
+      return {
+        ...props,
+        defaultOpen: undefined,
+        open: uncontrolledOpen,
+        onOpenChange: handleOpenChange,
+        delayDuration: delayDurationProp ?? 0,
+      };
+    }
+    return {
+      ...props,
+      onOpenChange: handleOpenChange,
+    };
+  })();
+
+  const contextValue: TooltipFieldContextValue = {
+    tapMode,
+    open: openSnapshot,
+    setOpen,
+    isControlled,
+    suppressFocusOpenRef,
+  };
+
+  return (
+    <TooltipFieldContext.Provider value={contextValue}>
+      <TooltipPrimitive.Root {...rootProps} />
+    </TooltipFieldContext.Provider>
+  );
+};
+Tooltip.displayName = TooltipPrimitive.Root.displayName;
+
+const TooltipTrigger = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Trigger>
+>(({ onPointerDown, onClick, ...props }, ref) => {
+  const { tapMode, open, setOpen, isControlled, suppressFocusOpenRef } = useTooltipFieldContext();
+
+  const onPointerDownForTap = React.useCallback(
+    (e: React.PointerEvent<HTMLButtonElement>) => {
+      if (tapMode) {
+        suppressFocusOpenRef.current = true;
+      }
+      if (tapMode && open) {
+        e.preventDefault();
+      }
+    },
+    [tapMode, open, suppressFocusOpenRef],
+  );
+
+  const onClickForTap = React.useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      if (!tapMode) {
+        return;
+      }
+      e.preventDefault();
+      if (isControlled) {
+        setOpen(!open);
+      } else {
+        setOpen((o) => !o);
+      }
+      suppressFocusOpenRef.current = false;
+    },
+    [tapMode, isControlled, open, setOpen, suppressFocusOpenRef],
+  );
+
+  /* Event-handler-only ref writes; rule misfires on composeEventHandlers + useCallback. */
+  /* eslint-disable react-hooks/refs -- suppressFocusOpenRef */
+  return (
+    <TooltipPrimitive.Trigger
+      ref={ref}
+      {...props}
+      onPointerDown={composeEventHandlers(onPointerDown, onPointerDownForTap)}
+      onClick={composeEventHandlers(onClick, onClickForTap)}
+    />
+  );
+  /* eslint-enable react-hooks/refs */
+});
+TooltipTrigger.displayName = TooltipPrimitive.Trigger.displayName;
 
 const TooltipContent = React.forwardRef(({ className, sideOffset = 4, ...props }: React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>, ref: React.Ref<React.ElementRef<typeof TooltipPrimitive.Content>>) => (
   <TooltipPrimitive.Portal>
@@ -8773,7 +9412,8 @@ var componentMetadata = {
     "dependencies": [
       "class-variance-authority",
       "clsx",
-      "tailwind-merge"
+      "tailwind-merge",
+      "lucide-react"
     ],
     "props": [],
     "variants": [],