@womp/kookie-ui 0.24.0 → 0.25.1

package/src/components/table.tsx

@@ -3,7 +3,7 @@ import classNames from 'classnames';
 
 import { tableRootPropDefs, tableRowPropDefs, tableCellPropDefs } from './table.props.js';
 import { extractProps } from '../helpers/extract-props.js';
-import { useThemeSizeProps } from '../helpers/theme-size.js';
+import { useThemeSizeProps } from '../hooks/theme-size.js';
 import { getResponsiveClassNames } from '../helpers/get-responsive-styles.js';
 import { ScrollArea } from './scroll-area.js';
 
@@ -35,7 +35,8 @@ const TableRoot = React.forwardRef<TableRootElement, TableRootProps>((ownProps,
   });
   return (
     <div ref={forwardedRef} className={classNames('kui-TableRoot', className)} {...rootProps}>
-      <ScrollArea>
+      {/* An overflowing scroller is a tab stop, so it carries the table's name and reads as a region. */}
+      <ScrollArea aria-label={ariaLabel} aria-labelledby={ariaLabelledBy}>
         <table
           className={classNames('kui-TableRootTable', tableLayoutClassNames)}
           aria-label={ariaLabel}

package/src/components/tabs.tsx

@@ -4,7 +4,7 @@ import { Tabs as TabsPrimitive } from 'radix-ui';
 
 import { tabsListPropDefs } from './tabs.props.js';
 import { extractProps } from '../helpers/extract-props.js';
-import { useThemeSizeProps } from '../helpers/theme-size.js';
+import { useThemeSizeProps } from '../hooks/theme-size.js';
 
 import type { tabsContentPropDefs, tabsRootPropDefs } from './tabs.props.js';
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
@@ -56,6 +56,11 @@ interface TabsTriggerProps
 const TabsTrigger = React.forwardRef<TabsTriggerElement, TabsTriggerProps>(
   (props, forwardedRef) => {
     const { className, children, ...triggerProps } = props;
+    // A hidden bold copy reserves the active width. Only plain text is copied: copying elements
+    // would duplicate their ids and mount them twice.
+    const isText = React.Children.toArray(children).every(
+      (child) => typeof child === 'string' || typeof child === 'number',
+    );
     return (
       <TabsPrimitive.Trigger
         {...triggerProps}
@@ -64,9 +69,11 @@ const TabsTrigger = React.forwardRef<TabsTriggerElement, TabsTriggerProps>(
         className={classNames('kui-reset', 'kui-BaseTabListTrigger', 'kui-TabsTrigger', className)}
       >
         <span className="kui-BaseTabListTriggerInner kui-TabsTriggerInner">{children}</span>
-        <span className="kui-BaseTabListTriggerInnerHidden kui-TabsTriggerInnerHidden">
-          {children}
-        </span>
+        {isText ? (
+          <span className="kui-BaseTabListTriggerInnerHidden kui-TabsTriggerInnerHidden" aria-hidden>
+            {children}
+          </span>
+        ) : null}
       </TabsPrimitive.Trigger>
     );
   },

package/src/components/text-area.css

@@ -19,8 +19,6 @@
 .kui-TextAreaRoot {
   display: flex;
   flex-direction: column;
-  /* The root spaces its parts: the gap sits between the text and an error message under it. */
-  gap: var(--space-2);
   box-sizing: border-box;
 
   font-family: var(--default-font-family);
@@ -481,7 +479,11 @@
  *                                                                                                 *
  ***************************************************************************************************/
 
+/* A sibling of the root, below the box: it takes the field's type itself. */
 .kui-TextAreaErrorMessage {
+  font-family: var(--default-font-family);
+  font-weight: var(--font-weight-regular);
+  padding-top: var(--space-2);
   color: var(--red-11);
   font-size: var(--font-size-1);
   line-height: var(--line-height-1);
@@ -496,3 +498,16 @@
   font-size: var(--font-size-1);
   line-height: 1;
 }
+
+/*
+ * Forced colors drop box-shadows, which draw every variant's boundary, so the box gets a real
+ * border there, as BaseButton does.
+ */
+@media (forced-colors: active) {
+  .kui-TextAreaRoot {
+    border: 1px solid CanvasText;
+  }
+  .kui-TextAreaRoot:where(:has(.kui-TextAreaInput:disabled)) {
+    border-color: GrayText;
+  }
+}

package/src/components/text-area.tsx

@@ -3,7 +3,7 @@ import classNames from 'classnames';
 
 import { textAreaPropDefs } from './text-area.props.js';
 import { extractProps } from '../helpers/extract-props.js';
-import { useThemeSizeProps } from '../helpers/theme-size.js';
+import { useThemeSizeProps } from '../hooks/theme-size.js';
 
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
 import type { GetPropDefTypes } from '../props/prop-def.js';
@@ -58,28 +58,32 @@ const TextArea = React.forwardRef<TextAreaElement, TextAreaProps>((ownProps, for
     ...nativeTextAreaProps
   } = textAreaProps;
 
+  // The message is a sibling of the painted root, so it sits below the box rather than inside it.
   return (
-    <div
-      data-accent-color={color}
-      data-radius={radius}
-      className={classNames('kui-TextAreaRoot', className, {
-        'kui-error': isInvalid,
-      })}
-      style={style}
-    >
-      <textarea
-        className="kui-reset kui-TextAreaInput"
-        ref={forwardedRef}
-        {...nativeTextAreaProps}
-        required={required || undefined}
-        {...ariaProps}
-      />
+    <>
+      <div
+        data-accent-color={color}
+        data-radius={radius}
+        className={classNames('kui-TextAreaRoot', className, {
+          // Not used by the library's CSS (invalid styling keys on aria-invalid); kept as a hook for app styles.
+          'kui-error': isInvalid,
+        })}
+        style={style}
+      >
+        <textarea
+          className="kui-reset kui-TextAreaInput"
+          ref={forwardedRef}
+          {...nativeTextAreaProps}
+          required={required || undefined}
+          {...ariaProps}
+        />
+      </div>
       {textAreaProps.errorMessage && (
         <div id={errorId} className="kui-TextAreaErrorMessage" role="alert">
           {textAreaProps.errorMessage}
         </div>
       )}
-    </div>
+    </>
   );
 });
 

package/src/components/text-field.css

@@ -74,13 +74,13 @@
     width: var(--text-field-native-icon-size);
     height: var(--text-field-native-icon-size);
     padding: var(--space-2);
-    margin-left: 0;
-    margin-right: calc(var(--space-2) * -1);
+    margin-inline-start: 0;
+    margin-inline-end: calc(var(--space-2) * -1);
     border-radius: calc(var(--text-field-border-radius) - 2px);
   }
   /* Chrome's calendar icon */
   &:where(:not([type='time']))::-webkit-calendar-picker-indicator {
-    margin-left: var(--space-2);
+    margin-inline-start: var(--space-2);
   }
   @media (hover: hover) {
     &::-webkit-calendar-picker-indicator:where(:hover) {
@@ -133,37 +133,37 @@
   }
 
   /*
-   * A slot that is not a right-side slot goes on the left.
+   * A slot that is not a right-side slot goes on the left (the inline start, so the right in RTL).
    * The outer edge keeps the plain padding (the slot stands between the text and a pill's curve);
    * the inner edge is the gap to the text.
    */
   &:where(:not([data-side='right'])) {
     order: -1;
-    margin-left: calc(var(--text-field-border-width) * -1);
-    margin-right: 0;
-    padding-left: var(--text-field-px);
-    padding-right: var(--text-field-gap);
+    margin-inline-start: calc(var(--text-field-border-width) * -1);
+    margin-inline-end: 0;
+    padding-inline-start: var(--text-field-px);
+    padding-inline-end: var(--text-field-gap);
 
     /* A hosted control sits the slot inset from the edge, the same distance as above and below. */
     &:where(:has(> .kui-BaseButton)) {
-      padding-left: var(--text-field-slot-inset);
+      padding-inline-start: var(--text-field-slot-inset);
     }
   }
 
   &:where([data-side='right']),
   /*
-   * A slot followed by a left-side slot that is not a left-side slot itself goes on the right.
+   * A slot followed by a left-side slot that is not a left-side slot itself goes on the right (the inline end).
    * In simple terms, this makes it so that two slots without an explicit side work automatically.
    */
   :where(&:not([data-side='right'])) ~ &:where(:not([data-side='left'])) {
     order: 0;
-    margin-left: 0;
-    margin-right: calc(var(--text-field-border-width) * -1);
-    padding-left: var(--text-field-gap);
-    padding-right: var(--text-field-px);
+    margin-inline-start: 0;
+    margin-inline-end: calc(var(--text-field-border-width) * -1);
+    padding-inline-start: var(--text-field-gap);
+    padding-inline-end: var(--text-field-px);
 
     &:where(:has(> .kui-BaseButton)) {
-      padding-right: var(--text-field-slot-inset);
+      padding-inline-end: var(--text-field-slot-inset);
     }
   }
 }
@@ -211,33 +211,33 @@
   /* Clip text to the border radius of the Root */
   border-radius: calc(var(--text-field-border-radius) - var(--text-field-border-width));
 
-  /* Equivalent to padding-left, but doesn't cut off long values when cursor is at the end. */
+  /* Equivalent to padding-inline-start, but doesn't cut off long values when cursor is at the end. */
   text-indent: calc(var(--text-field-px-bare) - var(--text-field-border-width));
-  padding-right: calc(var(--text-field-px-bare) - var(--text-field-border-width));
+  padding-inline-end: calc(var(--text-field-px-bare) - var(--text-field-border-width));
 
   &:where([type='date'], [type='datetime-local'], [type='time'], [type='week'], [type='month']) {
     /* Safari is buggy with text-indent for these input types */
     text-indent: 0;
-    padding-left: calc(var(--text-field-px-bare) - var(--text-field-border-width));
+    padding-inline-start: calc(var(--text-field-px-bare) - var(--text-field-border-width));
   }
 
-  /* Remove border-radius and text-indent/padding on the left if there's a left-side slot */
+  /* Remove border-radius and text-indent/padding at the inline start if there's a left-side slot */
   &:where(:has(~ .kui-TextFieldSlot:not([data-side='right']))) {
     text-indent: 0;
-    padding-left: 0;
-    border-top-left-radius: 0;
-    border-bottom-left-radius: 0;
+    padding-inline-start: 0;
+    border-start-start-radius: 0;
+    border-end-start-radius: 0;
   }
 
-  /* Remove border-radius and padding on the right if there's a right-side slot */
+  /* Remove border-radius and padding at the inline end if there's a right-side slot */
   /* prettier-ignore */
   &:where(:has(
     ~ .kui-TextFieldSlot[data-side='right'],
     ~ .kui-TextFieldSlot:not([data-side='right']) ~ .kui-TextFieldSlot:not([data-side='left'])
   )) {
-    padding-right: 0;
-    border-top-right-radius: 0;
-    border-bottom-right-radius: 0;
+    padding-inline-end: 0;
+    border-start-end-radius: 0;
+    border-end-end-radius: 0;
   }
 }
 
@@ -261,8 +261,8 @@
 
         /* Safari credentials autofill icon */
         &::-webkit-textfield-decoration-container {
-          padding-right: 0px;
-          margin-right: -2px;
+          padding-inline-end: 0px;
+          margin-inline-end: -2px;
         }
       }
     }
@@ -286,8 +286,8 @@
 
         /* Safari credentials autofill icon */
         &::-webkit-textfield-decoration-container {
-          padding-right: 2px;
-          margin-right: 0px;
+          padding-inline-end: 2px;
+          margin-inline-end: 0px;
         }
       }
     }
@@ -310,8 +310,8 @@
 
         /* Safari credentials autofill icon */
         &::-webkit-textfield-decoration-container {
-          padding-right: 5px;
-          margin-right: 0px;
+          padding-inline-end: 5px;
+          margin-inline-end: 0px;
         }
       }
     }
@@ -333,8 +333,8 @@
 
         /* Safari credentials autofill icon */
         &::-webkit-textfield-decoration-container {
-          padding-right: 5px;
-          margin-right: 0px;
+          padding-inline-end: 5px;
+          margin-inline-end: 0px;
         }
       }
     }
@@ -662,11 +662,13 @@
 
 /* Error message styling */
 .kui-TextFieldErrorMessage {
+  /* A sibling of the root, below the field: it takes the field's type itself. */
+  font-family: var(--default-font-family);
+  font-weight: var(--font-weight-regular);
   color: var(--red-11);
   font-size: var(--font-size-1);
   line-height: var(--line-height-1);
-  /* The field is a row, so a gap on the root would sit beside the message, not above it. The
-     drop is inside the message's own box, never a margin on it. */
+  /* The drop is inside the message's own box, never a margin on it. */
   padding-top: var(--space-2);
   display: flex;
   align-items: center;
@@ -680,6 +682,19 @@
   line-height: 1;
 }
 
+/*
+ * Forced colors drop box-shadows, which draw every variant's boundary, so the field gets a real
+ * border there, as BaseButton does.
+ */
+@media (forced-colors: active) {
+  .kui-TextFieldRoot {
+    border: 1px solid CanvasText;
+  }
+  .kui-TextFieldRoot:where(:has(.kui-TextFieldInput:disabled)) {
+    border-color: GrayText;
+  }
+}
+
 /***************************************************************************************************
  *                                                                                                 *
  * SCRUBBING                                                                                       *

package/src/components/text-field.tsx

@@ -3,11 +3,11 @@
 import * as React from 'react';
 import * as ReactDOM from 'react-dom';
 import classNames from 'classnames';
-import { composeRefs } from 'radix-ui/internal';
+import { composeEventHandlers, composeRefs } from 'radix-ui/internal';
 
 import { textFieldRootPropDefs, textFieldSlotPropDefs, type TextFieldSlotScrubProps } from './text-field.props.js';
 import { extractProps } from '../helpers/extract-props.js';
-import { useThemeSizeProps } from '../helpers/theme-size.js';
+import { useThemeSizeProps } from '../hooks/theme-size.js';
 
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
 import type { NotInputTextualAttributes } from '../helpers/input-attributes.js';
@@ -21,6 +21,15 @@ type TextFieldRootOwnProps = GetPropDefTypes<typeof textFieldRootPropDefs> & {
 };
 type TextFieldInputProps = ComponentPropsWithout<'input', NotInputTextualAttributes | 'color' | 'defaultValue' | 'size' | 'type' | 'value'>;
 interface TextFieldRootProps extends TextFieldInputProps, TextFieldRootOwnProps {}
+
+// Each Slot registers its id here, so the input can list slot content in aria-describedby.
+type TextFieldContextValue = { registerSlot: (id: string) => () => void };
+const TextFieldContext = React.createContext<TextFieldContextValue | null>(null);
+
+// Clicking anything a person could mean to press keeps its own press: the guard is a focusability
+// list, not a tag list. `[tabindex]` catches role-based widgets; `label` already redirects a click.
+const FOCUSABLE_IN_SLOT = 'button, a, input, select, textarea, label, [tabindex], [contenteditable]';
+
 const TextFieldRoot = React.forwardRef<TextFieldRootElement, TextFieldRootProps>((ownProps, forwardedRef) => {
   const props = useThemeSizeProps(ownProps, textFieldRootPropDefs.size);
   const inputRef = React.useRef<HTMLInputElement>(null);
@@ -29,18 +38,27 @@ const TextFieldRoot = React.forwardRef<TextFieldRootElement, TextFieldRootProps>
   // Generate unique IDs for accessibility
   const errorId = React.useId();
 
+  // Slot content qualifies the value, so it describes the input (as in v2), in mount order.
+  const [slotIds, setSlotIds] = React.useState<string[]>([]);
+  const registerSlot = React.useCallback((id: string) => {
+    setSlotIds((prev) => (prev.includes(id) ? prev : [...prev, id]));
+    return () => setSlotIds((prev) => prev.filter((slotId) => slotId !== id));
+  }, []);
+  const contextValue = React.useMemo(() => ({ registerSlot }), [registerSlot]);
+
   const { 'aria-describedby': ariaDescribedby, 'aria-labelledby': ariaLabelledby, 'aria-invalid': ariaInvalid } = inputProps;
 
   // Invalid when `error` is set or the caller passes aria-invalid; the CSS keys on aria-invalid only.
   const isInvalid = Boolean(inputProps.error) || ariaInvalid === true || ariaInvalid === 'true';
 
-  // Build aria-describedby string
+  // Build aria-describedby string. The caller's ids stay; ours are appended.
   const describedBy = React.useMemo(() => {
     const parts = [];
     if (inputProps.errorMessage) parts.push(errorId);
     if (ariaDescribedby) parts.push(ariaDescribedby);
+    parts.push(...slotIds);
     return parts.length > 0 ? parts.join(' ') : undefined;
-  }, [inputProps.errorMessage, ariaDescribedby, errorId]);
+  }, [inputProps.errorMessage, ariaDescribedby, errorId, slotIds]);
 
   // Build aria attributes
   const ariaProps = React.useMemo(
@@ -55,10 +73,11 @@ const TextFieldRoot = React.forwardRef<TextFieldRootElement, TextFieldRootProps>
   // Filter out our custom props to avoid DOM warnings
   const { error, errorMessage, required, 'aria-describedby': _ariaDescribedby, 'aria-labelledby': _ariaLabelledby, ...nativeInputProps } = inputProps;
 
-  // Memoized pointer event handler
-  const handlePointerDown = React.useCallback((event: React.PointerEvent) => {
+  // Clicking the padding or a passive slot focuses the input. preventDefault stops the browser
+  // from moving focus to the root first, so the input is focused once, synchronously.
+  const handleMouseDown = React.useCallback((event: React.MouseEvent) => {
     const target = event.target as HTMLElement;
-    if (target.closest('input, button, a')) return;
+    if (target.closest(FOCUSABLE_IN_SLOT)) return;
 
     const input = inputRef.current;
     if (!input) return;
@@ -71,34 +90,39 @@ const TextFieldRoot = React.forwardRef<TextFieldRootElement, TextFieldRootProps>
 
     const cursorPosition = isRightSlot ? input.value.length : 0;
 
-    requestAnimationFrame(() => {
-      // Only some input types support this, browsers will throw an error if not supported
-      // See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange#:~:text=Note%20that%20according,not%20support%20selection%22.
-      try {
-        input.setSelectionRange(cursorPosition, cursorPosition);
-      } catch {}
-      input.focus();
-    });
+    event.preventDefault();
+    input.focus();
+    // Only some input types support this, browsers will throw an error if not supported
+    // See: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange#:~:text=Note%20that%20according,not%20support%20selection%22.
+    try {
+      input.setSelectionRange(cursorPosition, cursorPosition);
+    } catch {}
   }, []);
 
+  // The message is a sibling of the painted root, so it sits below the field rather than inside it.
   return (
-    <div
-      data-accent-color={color}
-      data-radius={radius}
-      style={style}
-      className={classNames('kui-TextFieldRoot', className, {
-        'kui-error': isInvalid,
-      })}
-      onPointerDown={handlePointerDown}
-    >
-      <input {...nativeInputProps} required={required || undefined} {...ariaProps} ref={composeRefs(inputRef, forwardedRef)} className="kui-reset kui-TextFieldInput" />
-      {children}
+    <>
+      {/* A pointer-only hit-target redirect to the input; keyboard users reach the input directly. */}
+      {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions */}
+      <div
+        data-accent-color={color}
+        data-radius={radius}
+        style={style}
+        className={classNames('kui-TextFieldRoot', className, {
+          // Not used by the library's CSS (invalid styling keys on aria-invalid); kept as a hook for app styles.
+          'kui-error': isInvalid,
+        })}
+        onMouseDown={handleMouseDown}
+      >
+        <input {...nativeInputProps} required={required || undefined} {...ariaProps} ref={composeRefs(inputRef, forwardedRef)} className="kui-reset kui-TextFieldInput" />
+        <TextFieldContext.Provider value={contextValue}>{children}</TextFieldContext.Provider>
+      </div>
       {inputProps.errorMessage && (
         <div id={errorId} className="kui-TextFieldErrorMessage" role="alert">
           {inputProps.errorMessage}
         </div>
       )}
-    </div>
+    </>
   );
 });
 TextFieldRoot.displayName = 'TextField.Root';
@@ -122,12 +146,27 @@ const TextFieldSlot = React.forwardRef<TextFieldSlotElement, TextFieldSlotProps>
   const { scrub, scrubValue, scrubStep = 1, scrubSensitivity = 1, scrubMin, scrubMax, scrubShiftMultiplier = 10, scrubAltMultiplier = 0.1, onScrub, ...restProps } = props;
 
   // Then extract styling props
-  const { className, color, side, ...slotProps } = extractProps(restProps, textFieldSlotPropDefs);
+  const { className, color, side, onPointerDown, onPointerMove, onPointerUp, onLostPointerCapture, ...slotProps } = extractProps(
+    restProps,
+    textFieldSlotPropDefs,
+  );
+
+  // The slot describes the input (see TextFieldRoot); a caller's own id is kept.
+  const generatedId = React.useId();
+  const slotId = slotProps.id ?? generatedId;
+  const registerSlot = React.useContext(TextFieldContext)?.registerSlot;
+  React.useEffect(() => registerSlot?.(slotId), [registerSlot, slotId]);
 
   const slotRef = React.useRef<HTMLDivElement>(null);
   const [isScrubbing, setIsScrubbing] = React.useState(false);
-  // Virtual cursor position - X wraps around viewport, Y follows mouse
-  const [cursorPosition, setCursorPosition] = React.useState({ x: 0, y: 0 });
+  // Where the virtual cursor starts. Movement is written straight to the cursor element, so a
+  // scrub does not re-render the slot on every mouse move.
+  const [cursorStart, setCursorStart] = React.useState({ x: 0, y: 0 });
+  const cursorRef = React.useRef<HTMLImageElement>(null);
+  // Virtual cursor Y, tracked beside virtualX
+  const virtualY = React.useRef(0);
+  // Whether this slot asked for the pointer lock, so a lock change elsewhere is not ours
+  const lockedByMe = React.useRef(false);
 
   // Track accumulated sub-step movement for precision
   const accumulatedMovement = React.useRef(0);
@@ -168,7 +207,7 @@ const TextFieldSlot = React.forwardRef<TextFieldSlotElement, TextFieldSlotProps>
 
       // Don't start scrubbing if clicking on interactive elements
       const target = event.target as HTMLElement;
-      if (target.closest('input, button, a')) return;
+      if (target.closest(FOCUSABLE_IN_SLOT)) return;
 
       event.preventDefault();
       accumulatedMovement.current = 0;
@@ -177,7 +216,8 @@ const TextFieldSlot = React.forwardRef<TextFieldSlotElement, TextFieldSlotProps>
 
       // Initialize virtual cursor at actual mouse position
       virtualX.current = event.clientX;
-      setCursorPosition({ x: event.clientX, y: event.clientY });
+      virtualY.current = event.clientY;
+      setCursorStart({ x: event.clientX, y: event.clientY });
 
       const slot = slotRef.current;
       if (!slot) return;
@@ -190,20 +230,24 @@ const TextFieldSlot = React.forwardRef<TextFieldSlotElement, TextFieldSlotProps>
         setIsScrubbing(true);
       } else {
         // Chrome: Use pointer lock for infinite movement
+        lockedByMe.current = true;
         slot.requestPointerLock();
       }
     },
     [scrub, scrubValue],
   );
 
-  // Handle pointer lock state changes (Chrome only)
+  // Handle pointer lock state changes (Chrome only). Only a scrub slot listens, and only a lock
+  // this slot asked for starts or ends its scrub.
   React.useEffect(() => {
-    if (usePointerCapture) return;
+    if (usePointerCapture || !scrub) return;
 
     const handlePointerLockChange = () => {
+      if (!lockedByMe.current) return;
       const isLocked = document.pointerLockElement === slotRef.current;
       setIsScrubbing(isLocked);
       if (!isLocked) {
+        lockedByMe.current = false;
         // Fire callback with isChanging = false when scrubbing ends
         scrubConfigRef.current.onScrub?.(0, false);
         accumulatedMovement.current = 0;
@@ -215,7 +259,7 @@ const TextFieldSlot = React.forwardRef<TextFieldSlotElement, TextFieldSlotProps>
     return () => {
       document.removeEventListener('pointerlockchange', handlePointerLockChange);
     };
-  }, []);
+  }, [scrub]);
 
   // Shared scrub calculation logic
   const processScrubMovement = React.useCallback((movementX: number, movementY: number, shiftKey: boolean, altKey: boolean) => {
@@ -232,15 +276,19 @@ const TextFieldSlot = React.forwardRef<TextFieldSlotElement, TextFieldSlotProps>
     }
 
     // Also track Y with wrap-around
-    setCursorPosition((prev) => {
-      let newY = prev.y + movementY;
-      if (newY > viewportHeight) {
-        newY = newY % viewportHeight;
-      } else if (newY < 0) {
-        newY = viewportHeight + (newY % viewportHeight);
-      }
-      return { x: virtualX.current, y: newY };
-    });
+    let newY = virtualY.current + movementY;
+    if (newY > viewportHeight) {
+      newY = newY % viewportHeight;
+    } else if (newY < 0) {
+      newY = viewportHeight + (newY % viewportHeight);
+    }
+    virtualY.current = newY;
+
+    const cursor = cursorRef.current;
+    if (cursor) {
+      cursor.style.left = `${virtualX.current}px`;
+      cursor.style.top = `${newY}px`;
+    }
 
     // Accumulate movement for sensitivity calculation
     accumulatedMovement.current += movementX;
@@ -369,13 +417,14 @@ const TextFieldSlot = React.forwardRef<TextFieldSlotElement, TextFieldSlotProps>
   const virtualCursor = isScrubbing
     ? ReactDOM.createPortal(
         <img
+          ref={cursorRef}
           className="kui-TextFieldSlotScrubCursor"
           src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24'%3E%3Cpath fill='black' stroke='white' stroke-width='1' d='M0 12 L5 7 L5 10 L19 10 L19 7 L24 12 L19 17 L19 14 L5 14 L5 17 Z'/%3E%3C/svg%3E"
           alt=""
           style={{
             position: 'fixed',
-            left: cursorPosition.x,
-            top: cursorPosition.y,
+            left: cursorStart.x,
+            top: cursorStart.y,
             transform: 'translate(-50%, -50%)',
             pointerEvents: 'none',
             zIndex: 99999,
@@ -395,12 +444,14 @@ const TextFieldSlot = React.forwardRef<TextFieldSlotElement, TextFieldSlotProps>
       data-scrub={scrub || undefined}
       data-scrubbing={isScrubbing || undefined}
       {...slotProps}
+      id={slotId}
       ref={composeRefs(slotRef, forwardedRef)}
       className={classNames('kui-TextFieldSlot', className)}
-      onPointerDown={scrub ? handlePointerDown : undefined}
-      onPointerMove={scrub ? handlePointerMove : undefined}
-      onPointerUp={scrub ? handlePointerUp : undefined}
-      onLostPointerCapture={scrub ? handleLostPointerCapture : undefined}
+      // The caller's handlers run first; the scrub handlers only when `scrub` is set.
+      onPointerDown={scrub ? composeEventHandlers(onPointerDown, handlePointerDown) : onPointerDown}
+      onPointerMove={scrub ? composeEventHandlers(onPointerMove, handlePointerMove) : onPointerMove}
+      onPointerUp={scrub ? composeEventHandlers(onPointerUp, handlePointerUp) : onPointerUp}
+      onLostPointerCapture={scrub ? composeEventHandlers(onLostPointerCapture, handleLostPointerCapture) : onLostPointerCapture}
     >
       {slotProps.children}
       {virtualCursor}