@kushagradhawan/kookie-ui 0.1.78 → 0.1.79

package/src/components/combobox.tsx

@@ -29,6 +29,14 @@ import type { GetPropDefTypes } from '../props/prop-def.js';
 
 type TextFieldVariant = (typeof textFieldRootPropDefs.variant.values)[number];
 type ComboboxValue = string | null;
+/**
+ * Custom filter function for Combobox search.
+ * @param value - The item's value being tested
+ * @param search - The current search string
+ * @param keywords - Optional keywords associated with the item
+ * @returns A number between 0 and 1 where 0 means no match and 1 means exact match.
+ *          Fractional values indicate relevance for sorting.
+ */
 type CommandFilter = (value: string, search: string, keywords?: string[]) => number;
 
 /**
@@ -50,6 +58,42 @@ type ComboboxRootOwnProps = GetPropDefTypes<typeof comboboxRootPropDefs> & {
   shouldFilter?: boolean;
   loop?: boolean;
   disabled?: boolean;
+  /**
+   * Whether to reset the search value when an option is selected.
+   * @default true
+   */
+  resetSearchOnSelect?: boolean;
+  /**
+   * Accent color for the combobox trigger and content.
+   */
+  color?: (typeof comboboxTriggerPropDefs.color.values)[number];
+  /**
+   * Display value shown in the trigger. This is the recommended approach for
+   * best performance as it avoids needing to mount items to register labels.
+   * 
+   * Can be either:
+   * - A string: Static display value
+   * - A function: `(value: string | null) => string | undefined` - Called with current value
+   * 
+   * Use this when:
+   * - You have the selected item's label available (e.g., from your data source)
+   * - Items haven't mounted yet (e.g., on initial render with a defaultValue)
+   * - You want optimal performance with forceMount={false} (default)
+   * 
+   * @example
+   * // Static string
+   * <Combobox.Root value="usa" displayValue="United States">
+   * 
+   * // Function (recommended for dynamic data)
+   * <Combobox.Root 
+   *   value={selectedCountry}
+   *   displayValue={(value) => countries.find(c => c.code === value)?.name}
+   * >
+   * 
+   * If not provided, falls back to the label registered by the selected item
+   * (requires forceMount={true}), then to the raw value.
+   */
+  displayValue?: string | ((value: ComboboxValue) => string | undefined);
 };
 
 /**
@@ -62,9 +106,16 @@ interface ComboboxContextValue extends ComboboxRootOwnProps {
   setValue: (value: ComboboxValue) => void;
   searchValue: string;
   setSearchValue: (value: string) => void;
+  /** Label registered by the selected item */
   selectedLabel?: string;
+  /** Resolved display value (already computed from string or function) */
+  resolvedDisplayValue?: string;
   registerItemLabel: (value: string, label: string) => void;
+  unregisterItemLabel: (value: string) => void;
   handleSelect: (value: string) => void;
+  listboxId: string;
+  activeDescendantId: string | undefined;
+  setActiveDescendantId: (id: string | undefined) => void;
 }
 
 const ComboboxContext = React.createContext<ComboboxContextValue | null>(null);
@@ -116,9 +167,17 @@ const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
     shouldFilter = true,
     loop = true,
     disabled,
+    resetSearchOnSelect = true,
+    color,
+    displayValue: displayValueProp,
     ...rootProps
   } = props;
 
+  // Generate stable IDs for accessibility
+  const generatedId = React.useId();
+  const listboxId = `combobox-listbox-${generatedId}`;
+  const [activeDescendantId, setActiveDescendantId] = React.useState<string | undefined>(undefined);
+
   const [open, setOpen] = useControllableState({
     prop: openProp,
     defaultProp: defaultOpen,
@@ -138,21 +197,67 @@ const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
   });
 
   const labelMapRef = React.useRef(new Map<string, string>());
+  // Track the selected label in state so it triggers re-renders when items register
+  const [selectedLabel, setSelectedLabel] = React.useState<string | undefined>(undefined);
+
   const registerItemLabel = React.useCallback((itemValue: string, label: string) => {
     labelMapRef.current.set(itemValue, label);
+    // If this item matches the current value, update the selected label
+    if (itemValue === value) {
+      setSelectedLabel(label);
+    }
+  }, [value]);
+
+  const unregisterItemLabel = React.useCallback((itemValue: string) => {
+    labelMapRef.current.delete(itemValue);
   }, []);
 
-  const selectedLabel = value != null ? labelMapRef.current.get(value) : undefined;
+  // Update selected label when value changes
+  React.useEffect(() => {
+    if (value != null) {
+      const label = labelMapRef.current.get(value);
+      setSelectedLabel(label);
+    } else {
+      setSelectedLabel(undefined);
+    }
+  }, [value]);
 
   const handleSelect = React.useCallback(
     (nextValue: string) => {
       setValue(nextValue);
       setOpen(false);
-      setSearchValue('');
+      if (resetSearchOnSelect) {
+        setSearchValue('');
+      }
     },
-    [setOpen, setSearchValue, setValue],
+    [setOpen, setSearchValue, setValue, resetSearchOnSelect],
   );
 
+  // Development mode warning for value not matching any registered item
+  React.useEffect(() => {
+    if (process.env.NODE_ENV !== 'production' && value != null && !labelMapRef.current.has(value)) {
+      // Defer the check to allow items to register first
+      const timeoutId = setTimeout(() => {
+        if (value != null && !labelMapRef.current.has(value)) {
+          console.warn(
+            `[Combobox] The value "${value}" does not match any Combobox.Item. ` +
+              `Make sure each Item has a matching value prop.`,
+          );
+        }
+      }, 0);
+      return () => clearTimeout(timeoutId);
+    }
+  }, [value]);
+
+  // Resolve displayValue: compute if function, use directly if string
+  const resolvedDisplayValue = React.useMemo(() => {
+    if (displayValueProp == null) return undefined;
+    if (typeof displayValueProp === 'function') {
+      return displayValueProp(value);
+    }
+    return displayValueProp;
+  }, [displayValueProp, value]);
+
   const contextValue = React.useMemo<ComboboxContextValue>(
     () => ({
       size,
@@ -163,6 +268,9 @@ const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
       shouldFilter,
       loop,
       disabled,
+      resetSearchOnSelect,
+      color,
+      resolvedDisplayValue,
       open,
       setOpen,
       value,
@@ -171,7 +279,11 @@ const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
       setSearchValue,
       selectedLabel,
       registerItemLabel,
+      unregisterItemLabel,
       handleSelect,
+      listboxId,
+      activeDescendantId,
+      setActiveDescendantId,
     }),
     [
       size,
@@ -182,6 +294,9 @@ const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
       shouldFilter,
       loop,
       disabled,
+      resetSearchOnSelect,
+      color,
+      resolvedDisplayValue,
       open,
       setOpen,
       value,
@@ -190,7 +305,11 @@ const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
       setSearchValue,
       selectedLabel,
       registerItemLabel,
+      unregisterItemLabel,
       handleSelect,
+      listboxId,
+      activeDescendantId,
+      setActiveDescendantId,
     ],
   );
 
@@ -225,13 +344,22 @@ const ComboboxTrigger = React.forwardRef<ComboboxTriggerElement, ComboboxTrigger
   const { material, panelBackground } = props;
 
   const isDisabled = disabled ?? context.disabled;
+
+  // Use color from props or fall back to context color
+  const resolvedColor = color ?? context.color;
+
+  // Comprehensive ARIA attributes for combobox pattern (WAI-ARIA 1.2)
   const ariaProps = React.useMemo(
     () => ({
+      role: 'combobox' as const,
       'aria-expanded': context.open,
       'aria-disabled': isDisabled || undefined,
       'aria-haspopup': 'listbox' as const,
+      'aria-controls': context.open ? context.listboxId : undefined,
+      'aria-activedescendant': context.open ? context.activeDescendantId : undefined,
+      'aria-autocomplete': 'list' as const,
     }),
-    [context.open, isDisabled],
+    [context.open, context.listboxId, context.activeDescendantId, isDisabled],
   );
 
   const defaultContent = (
@@ -256,7 +384,7 @@ const ComboboxTrigger = React.forwardRef<ComboboxTriggerElement, ComboboxTrigger
 
   const triggerChild = (
     <button
-      data-accent-color={color}
+      data-accent-color={resolvedColor}
       data-radius={radius}
       data-panel-background={panelBackground}
       data-material={material}
@@ -286,10 +414,13 @@ interface ComboboxValueProps extends React.ComponentPropsWithoutRef<'span'> {
 /**
  * Value mirrors Select.Value by showing the selected item's label
  * or falling back to placeholder text supplied by the consumer or context.
+ * 
+ * Priority: resolvedDisplayValue (explicit) > selectedLabel (from items) > raw value > children > placeholder
  */
 const ComboboxValue = React.forwardRef<ComboboxValueElement, ComboboxValueProps>(({ placeholder, children, className, ...valueProps }, forwardedRef) => {
   const context = useComboboxContext('Combobox.Value');
-  const displayValue = context.selectedLabel ?? context.value ?? undefined;
+  // Priority: explicit displayValue (resolved) > registered label > raw value
+  const displayValue = context.resolvedDisplayValue ?? context.selectedLabel ?? context.value ?? undefined;
   const fallback = placeholder ?? context.placeholder;
   return (
     <span {...valueProps} ref={forwardedRef} className={classNames('rt-ComboboxValue', className)}>
@@ -321,16 +452,28 @@ const ComboboxContent = React.forwardRef<ComboboxContentElement, ComboboxContent
     { ...props, size: sizeProp, variant: variantProp, highContrast: highContrastProp },
     comboboxContentPropDefs,
   );
-  const resolvedColor = color || themeContext.accentColor;
-  let sanitizedClassName = className;
-  if (typeof sizeProp === 'string') {
-    sanitizedClassName =
-      className
-        ?.split(/\s+/)
-        .filter(Boolean)
-        .filter((token) => !/^rt-r-size-\d$/.test(token))
-        .join(' ') || undefined;
-  }
+  const resolvedColor = color || context.color || themeContext.accentColor;
+  
+  // Memoize className sanitization to avoid string operations on every render
+  const sanitizedClassName = React.useMemo(() => {
+    if (typeof sizeProp !== 'string') return className;
+    return className
+      ?.split(/\s+/)
+      .filter(Boolean)
+      .filter((token) => !/^rt-r-size-\d$/.test(token))
+      .join(' ') || undefined;
+  }, [className, sizeProp]);
+
+  /**
+   * forceMount behavior:
+   * - When true: Content stays mounted when closed, allowing items to register labels
+   *   for display in the trigger. Use this if you need dynamic label resolution.
+   * - When false/undefined (default): Content unmounts when closed for better performance.
+   *   Use the `displayValue` prop on Root to show the selected label instead.
+   * 
+   * For best performance with large lists, keep forceMount=undefined and provide displayValue.
+   */
+  const shouldForceMount = forceMount === true ? true : undefined;
 
   return (
     <Popover.Content
@@ -342,7 +485,7 @@ const ComboboxContent = React.forwardRef<ComboboxContentElement, ComboboxContent
       sideOffset={4}
       collisionPadding={10}
       {...contentProps}
-      forceMount={forceMount}
+      forceMount={shouldForceMount}
       container={container}
       ref={forwardedRef}
       className={classNames('rt-PopperContent', 'rt-BaseMenuContent', 'rt-ComboboxContent', sanitizedClassName)}
@@ -351,8 +494,6 @@ const ComboboxContent = React.forwardRef<ComboboxContentElement, ComboboxContent
         <ComboboxContentContext.Provider value={{ variant: variantProp, size: String(sizeProp), color: resolvedColor, material: effectiveMaterial, highContrast: highContrastProp }}>
           <CommandPrimitive
             loop={context.loop}
-            value={context.searchValue}
-            onValueChange={context.setSearchValue}
             shouldFilter={context.shouldFilter}
             filter={context.filter}
             className="rt-ComboboxCommand"
@@ -367,25 +508,38 @@ const ComboboxContent = React.forwardRef<ComboboxContentElement, ComboboxContent
 ComboboxContent.displayName = 'Combobox.Content';
 
 type ComboboxInputElement = React.ElementRef<typeof CommandPrimitive.Input>;
-interface ComboboxInputProps extends React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input> {
+interface ComboboxInputProps extends Omit<React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>, 'value' | 'onValueChange'> {
   startAdornment?: React.ReactNode;
   endAdornment?: React.ReactNode;
   variant?: TextFieldVariant;
+  /** Controlled search value. Falls back to Root's searchValue if not provided. */
+  value?: string;
+  /** Callback when search value changes. Falls back to Root's onSearchValueChange if not provided. */
+  onValueChange?: (value: string) => void;
 }
 /**
  * Input composes TextField tokens with cmdk's Command.Input to provide
  * automatic focus management and optional adornments.
  */
-const ComboboxInput = React.forwardRef<ComboboxInputElement, ComboboxInputProps>(({ className, startAdornment, endAdornment, placeholder, variant: inputVariant, ...inputProps }, forwardedRef) => {
+const ComboboxInput = React.forwardRef<ComboboxInputElement, ComboboxInputProps>(({ className, startAdornment, endAdornment, placeholder, variant: inputVariant, value, onValueChange, ...inputProps }, forwardedRef) => {
   const context = useComboboxContext('Combobox.Input');
   const contentContext = useComboboxContentContext();
   const contentVariant = contentContext?.variant ?? 'solid';
   const color = contentContext?.color;
   const material = contentContext?.material;
 
-  // Map combobox variant to textfield variant: solid -> surface, soft -> soft unless overridden
+  /**
+   * Map combobox content variant to TextField variant:
+   * - Content 'solid' → Input 'surface' (elevated input on solid background)
+   * - Content 'soft' → Input 'soft' (subtle input on soft background)
+   * This ensures visual harmony between the input and surrounding content.
+   */
   const textFieldVariant = inputVariant ?? (contentVariant === 'solid' ? 'surface' : 'soft');
 
+  // Use controlled search value from context, allow override via props
+  const searchValue = value ?? context.searchValue;
+  const handleSearchChange = onValueChange ?? context.setSearchValue;
+
   const inputField = (
     <div
       className={classNames('rt-TextFieldRoot', 'rt-ComboboxInputRoot', `rt-r-size-${context.size}`, `rt-variant-${textFieldVariant}`)}
@@ -394,7 +548,14 @@ const ComboboxInput = React.forwardRef<ComboboxInputElement, ComboboxInputProps>
       data-panel-background={material}
     >
       {startAdornment ? <div className="rt-TextFieldSlot">{startAdornment}</div> : null}
-      <CommandPrimitive.Input {...inputProps} ref={forwardedRef} placeholder={placeholder ?? context.searchPlaceholder} className={classNames('rt-reset', 'rt-TextFieldInput', className)} />
+      <CommandPrimitive.Input
+        {...inputProps}
+        ref={forwardedRef}
+        value={searchValue}
+        onValueChange={handleSearchChange}
+        placeholder={placeholder ?? context.searchPlaceholder}
+        className={classNames('rt-reset', 'rt-TextFieldInput', className)}
+      />
       {endAdornment ? (
         <div className="rt-TextFieldSlot" data-side="right">
           {endAdornment}
@@ -415,14 +576,68 @@ type ComboboxListElement = React.ElementRef<typeof CommandPrimitive.List>;
 interface ComboboxListProps extends React.ComponentPropsWithoutRef<typeof CommandPrimitive.List> {}
 /**
  * List wraps cmdk's Command.List to inherit base menu styles and provides ScrollArea for the items.
+ * Also handles aria-activedescendant tracking via a single MutationObserver for all items.
  */
-const ComboboxList = React.forwardRef<ComboboxListElement, ComboboxListProps>(({ className, ...listProps }, forwardedRef) => (
-  <ScrollArea type="auto" className="rt-ComboboxScrollArea" scrollbars="vertical" size="1">
-    <div className={classNames('rt-BaseMenuViewport', 'rt-ComboboxViewport')}>
-      <CommandPrimitive.List {...listProps} ref={forwardedRef} className={classNames('rt-ComboboxList', className)} />
-    </div>
-  </ScrollArea>
-));
+const ComboboxList = React.forwardRef<ComboboxListElement, ComboboxListProps>(({ className, ...listProps }, forwardedRef) => {
+  const context = useComboboxContext('Combobox.List');
+  const listRef = React.useRef<HTMLDivElement | null>(null);
+
+  // Combined ref handling
+  const combinedRef = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      listRef.current = node;
+      if (typeof forwardedRef === 'function') {
+        forwardedRef(node);
+      } else if (forwardedRef) {
+        (forwardedRef as React.MutableRefObject<HTMLDivElement | null>).current = node;
+      }
+    },
+    [forwardedRef],
+  );
+
+  /**
+   * Single MutationObserver at List level to track aria-activedescendant.
+   * This replaces per-item observers for better performance with large lists.
+   */
+  React.useEffect(() => {
+    const listNode = listRef.current;
+    if (!listNode) return;
+
+    const updateActiveDescendant = () => {
+      const selectedItem = listNode.querySelector('[data-selected="true"], [aria-selected="true"]');
+      const itemId = selectedItem?.id;
+      context.setActiveDescendantId(itemId || undefined);
+    };
+
+    // Initial check
+    updateActiveDescendant();
+
+    // Watch for attribute changes on any descendant
+    const observer = new MutationObserver(updateActiveDescendant);
+    observer.observe(listNode, {
+      attributes: true,
+      attributeFilter: ['data-selected', 'aria-selected'],
+      subtree: true,
+    });
+
+    return () => observer.disconnect();
+  }, [context.setActiveDescendantId]);
+
+  return (
+    <ScrollArea type="auto" className="rt-ComboboxScrollArea" scrollbars="vertical" size="1">
+      <div className={classNames('rt-BaseMenuViewport', 'rt-ComboboxViewport')}>
+        <CommandPrimitive.List
+          {...listProps}
+          ref={combinedRef}
+          id={context.listboxId}
+          role="listbox"
+          aria-label="Options"
+          className={classNames('rt-ComboboxList', className)}
+        />
+      </div>
+    </ScrollArea>
+  );
+});
 ComboboxList.displayName = 'Combobox.List';
 
 type ComboboxEmptyElement = React.ElementRef<typeof CommandPrimitive.Empty>;
@@ -463,77 +678,93 @@ const ComboboxSeparator = React.forwardRef<ComboboxSeparatorElement, ComboboxSep
 ComboboxSeparator.displayName = 'Combobox.Separator';
 
 type ComboboxItemElement = React.ElementRef<typeof CommandPrimitive.Item>;
-interface ComboboxItemProps extends React.ComponentPropsWithoutRef<typeof CommandPrimitive.Item> {
+interface ComboboxItemProps extends Omit<React.ComponentPropsWithoutRef<typeof CommandPrimitive.Item>, 'keywords'> {
+  /** Display label for the item. Also used for search unless keywords are provided. */
   label?: string;
+  /** Additional keywords for search filtering (overrides automatic label-based search). */
+  keywords?: string[];
 }
 /**
  * Item wires cmdk's selection handling with Kookie UI tokens and
  * ensures labels are registered for displaying the current value.
  */
-const ComboboxItem = React.forwardRef<ComboboxItemElement, ComboboxItemProps>(({ className, children, label, value, disabled, onSelect, ...itemProps }, forwardedRef) => {
+/**
+ * Extracts text content from React children recursively.
+ * Used to derive searchable labels from JSX children.
+ */
+function extractTextFromChildren(children: React.ReactNode): string {
+  if (typeof children === 'string') return children;
+  if (typeof children === 'number') return String(children);
+  if (children == null || typeof children === 'boolean') return '';
+  if (Array.isArray(children)) {
+    return children.map(extractTextFromChildren).filter(Boolean).join(' ');
+  }
+  if (React.isValidElement(children)) {
+    const props = children.props as { children?: React.ReactNode };
+    if (props.children) {
+      return extractTextFromChildren(props.children);
+    }
+  }
+  return '';
+}
+
+const ComboboxItem = React.forwardRef<ComboboxItemElement, ComboboxItemProps>(({ className, children, label, value, disabled, onSelect, keywords, ...itemProps }, forwardedRef) => {
   const context = useComboboxContext('Combobox.Item');
   const contentContext = useComboboxContentContext();
-  const itemLabel = label ?? (typeof children === 'string' ? children : String(value));
+  
+  // Memoize label extraction to avoid recursive traversal on every render
+  const extractedLabel = React.useMemo(() => extractTextFromChildren(children), [children]);
+  const itemLabel = label ?? (extractedLabel || String(value));
   const isSelected = value != null && context.value === value;
   const sizeClass = contentContext?.size ? `rt-r-size-${contentContext.size}` : undefined;
 
+  // Use provided keywords, or default to the item label for search
+  // This allows searching by display text even when value is different (e.g., "usa" vs "United States")
+  const searchKeywords = keywords ?? [itemLabel];
+
+  // Generate stable ID for this item for aria-activedescendant
+  const generatedId = React.useId();
+  const itemId = `combobox-item-${generatedId}`;
+
+  // Destructure stable references to avoid effect re-runs when unrelated context values change
+  const { registerItemLabel, unregisterItemLabel, handleSelect: contextHandleSelect } = context;
+
+  // Register/unregister label for display in trigger
   React.useEffect(() => {
     if (value) {
-      context.registerItemLabel(value, itemLabel);
+      registerItemLabel(value, itemLabel);
+      return () => unregisterItemLabel(value);
     }
-  }, [context, value, itemLabel]);
+  }, [registerItemLabel, unregisterItemLabel, value, itemLabel]);
 
   const handleSelect = React.useCallback(
     (selectedValue: string) => {
-      context.handleSelect(selectedValue);
+      contextHandleSelect(selectedValue);
       onSelect?.(selectedValue);
     },
-    [context, onSelect],
+    [contextHandleSelect, onSelect],
   );
 
   const isDisabled = disabled ?? context.disabled ?? false;
 
-  // Internal ref to clean up data-disabled attribute
-  const internalRef = React.useRef<ComboboxItemElement | null>(null);
-
-  // Ref callback to handle both forwarded ref and internal ref
-  const itemRef = React.useCallback(
-    (node: ComboboxItemElement | null) => {
-      internalRef.current = node;
-      if (typeof forwardedRef === 'function') {
-        forwardedRef(node);
-      } else if (forwardedRef) {
-        (forwardedRef as React.MutableRefObject<ComboboxItemElement | null>).current = node;
-      }
-    },
-    [forwardedRef],
-  );
-
-  // Remove data-disabled attribute if cmdk sets it incorrectly
-  React.useEffect(() => {
-    if (!isDisabled && internalRef.current) {
-      const node = internalRef.current;
-      // Check and remove immediately
-      if (node.getAttribute('data-disabled') === 'false' || node.getAttribute('data-disabled') === '') {
-        node.removeAttribute('data-disabled');
-      }
-      // Also watch for changes
-      const observer = new MutationObserver(() => {
-        if (node.getAttribute('data-disabled') === 'false' || node.getAttribute('data-disabled') === '') {
-          node.removeAttribute('data-disabled');
-        }
-      });
-      observer.observe(node, { attributes: true, attributeFilter: ['data-disabled'] });
-      return () => observer.disconnect();
-    }
-  }, [isDisabled]);
+  /**
+   * Performance notes:
+   * - data-disabled workaround: Handled via CSS selectors in combobox.css
+   *   rather than per-item MutationObservers.
+   * - aria-activedescendant: Tracked by a single observer in ComboboxList
+   *   rather than per-item observers.
+   */
 
   return (
     <CommandPrimitive.Item
       {...itemProps}
+      id={itemId}
       value={value}
-      {...(isDisabled ? { disabled: true } : {})}
-      ref={itemRef}
+      keywords={searchKeywords}
+      role="option"
+      aria-selected={isSelected}
+      {...(isDisabled ? { disabled: true, 'aria-disabled': true } : {})}
+      ref={forwardedRef}
       onSelect={handleSelect}
       className={classNames('rt-reset', 'rt-BaseMenuItem', 'rt-ComboboxItem', className)}
     >
@@ -564,6 +795,7 @@ export {
 export type {
   ComboboxRootProps as RootProps,
   ComboboxTriggerProps as TriggerProps,
+  ComboboxValueProps as ValueProps,
   ComboboxContentProps as ContentProps,
   ComboboxInputProps as InputProps,
   ComboboxListProps as ListProps,

package/src/components/text-field.css

@@ -852,3 +852,86 @@
   font-size: var(--font-size-1);
   line-height: 1;
 }
+
+/***************************************************************************************************
+ *                                                                                                 *
+ * SCRUBBING                                                                                       *
+ *                                                                                                 *
+ ***************************************************************************************************/
+
+/* Scrub-enabled slot hover state */
+.rt-TextFieldSlot:where([data-scrub]) {
+  cursor: ew-resize !important;
+  user-select: none;
+  position: relative;
+}
+
+/* Ensure children also show ew-resize cursor */
+.rt-TextFieldSlot:where([data-scrub]) * {
+  cursor: ew-resize !important;
+}
+
+/* Active scrubbing state - hide real cursor */
+.rt-TextFieldSlot:where([data-scrubbing]) {
+  cursor: none;
+}
+
+/* Hide cursor on entire document body during scrubbing via pointer capture */
+.rt-TextFieldSlot:where([data-scrubbing]) * {
+  cursor: none;
+}
+
+/* Virtual cursor indicator - viewport-wide floating cursor */
+.rt-TextFieldSlotScrubCursor {
+  /* Position is set inline via JS */
+  width: 20px;
+  height: 20px;
+  background-color: var(--accent-9);
+  border-radius: 50%;
+  pointer-events: none;
+  
+  /* Subtle glow effect */
+  box-shadow: 
+    0 0 0 2px var(--color-background),
+    0 0 8px var(--accent-a8),
+    0 0 16px var(--accent-a6);
+}
+
+/* Left/right arrows to indicate scrub direction */
+.rt-TextFieldSlotScrubCursor::before,
+.rt-TextFieldSlotScrubCursor::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  width: 0;
+  height: 0;
+  border-style: solid;
+  transform: translateY(-50%);
+}
+
+/* Left arrow */
+.rt-TextFieldSlotScrubCursor::before {
+  left: -10px;
+  border-width: 5px 6px 5px 0;
+  border-color: transparent var(--accent-9) transparent transparent;
+}
+
+/* Right arrow */
+.rt-TextFieldSlotScrubCursor::after {
+  right: -10px;
+  border-width: 5px 0 5px 6px;
+  border-color: transparent transparent transparent var(--accent-9);
+}
+
+/* Visual feedback during scrubbing - subtle highlight on the slot */
+.rt-TextFieldSlot:where([data-scrubbing]) {
+  background-color: var(--accent-a3);
+  border-radius: calc(var(--text-field-border-radius, var(--radius-2)) - 2px);
+}
+
+/* Reduced motion support - hide glow animations */
+@media (prefers-reduced-motion: reduce) {
+  .rt-TextFieldSlotScrubCursor {
+    box-shadow: 0 0 0 2px var(--color-background);
+  }
+}