@astryxdesign/core 0.7.8 → 0.7.9-canary.0236bb8

package/src/hooks/useMenuPress.ts

@@ -6,7 +6,8 @@
  * @file useMenuPress.ts
  * @input The menu root, its trigger, the enabled-row selector, and callbacks
  *   for opening, highlighting, activating and dismissing
- * @output useMenuPress, the marker attributes, and the activation mark
+ * @output useMenuPress, the marker attributes, the activation mark, and the
+ *   internal useDropdownMenuPress entry with its touch model
  * @position Core hook for DropdownMenu, ContextMenu, DropdownMenuSubMenu,
  *   Selector and MenuBottomSheetActionList. The transition table lives in
  *   menuPressGesture.ts.
@@ -29,10 +30,10 @@ import {
 import {currentGesture} from '../Layer/gestureCounter';
 import {
   IDLE_MENU_PRESS,
-  menuPressStep,
-  type MenuPressEffect,
-  type MenuPressEvent,
-  type MenuPressGesture,
+  menuPressTransition,
+  type MenuPressOutcome,
+  type MenuPressInput,
+  type MenuPressState,
   type MenuPressPointerType,
 } from './menuPressGesture';
 import {MENU_PRESS_MARKER} from './menuPressMarker';
@@ -45,6 +46,12 @@ import {edgeAutoscroll} from '../utils/edgeAutoscroll';
 import {focusForLastInput} from '../utils/focusReturn';
 import {useInteractionModalityTrackingFor} from '../utils/interactionModality';
 import {LONG_PRESS_DURATION_MS} from '../motion/uikit/longPress';
+import {
+  clearMenuPressLit,
+  holdMenuPressPaint,
+  markMenuPressLit,
+  releaseMenuPressPaint,
+} from '../privateAttributes/menuPressLit.stylex';
 import {
   __resetClickGuardForTest,
   armClickGuard,
@@ -235,6 +242,44 @@ interface ResolvedPoint {
   isOnTrigger: boolean;
 }
 
+/**
+ * DropdownMenu's options for the press model: everything the public hook
+ * takes, plus its touch model. DropdownMenu reaches the touch model through
+ * its `presentation`, so the public hook has no such option.
+ *
+ * @internal
+ */
+export interface DropdownMenuPressOptions extends UseMenuPressOptions {
+  /**
+   * How the finger that opened the menu from the trigger picks.
+   * `'pointer'`: its opening press follows the settle rule. `'uikit'`: it
+   * picks only after UIMenu's handoff distance, so the row that appeared
+   * under it never acts on a still lift. A mouse is unaffected.
+   * @default 'pointer'
+   */
+  touchModel?: 'pointer' | 'uikit';
+}
+
+/**
+ * What core's own menus get from {@link useDropdownMenuPress}: the public
+ * return. Not exported from the hooks entry point.
+ *
+ * @internal
+ */
+export type DropdownMenuPressReturn = UseMenuPressReturn;
+
+/**
+ * Where a pointer is, for a finger's handoff distance. Positions reach the
+ * machine only under `touchModel: 'uikit'`. Without them, it keeps the settle
+ * rule.
+ */
+function handoffPosition(
+  event: PointerEvent,
+  hasHandoff: boolean,
+): {x?: number; y?: number} {
+  return hasHandoff ? {x: event.clientX, y: event.clientY} : {};
+}
+
 /**
  * The press model for a menu: the row under the release acts, the highlight
  * follows a held pointer, and a mouse opens the menu on press.
@@ -271,13 +316,30 @@ interface ResolvedPoint {
  * ```
  */
 export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
+  // The touch model is DropdownMenu's alone; an untyped caller's
+  // `touchModel` does not reach the model.
+  const {touchModel: _touchModel, ...publicOptions} =
+    options as DropdownMenuPressOptions;
+  return useDropdownMenuPress({...publicOptions, touchModel: 'pointer'});
+}
+
+/**
+ * The press model with DropdownMenu's touch model
+ * ({@link DropdownMenuPressOptions.touchModel}). Not exported from the hooks
+ * entry point.
+ *
+ * @internal
+ */
+export function useDropdownMenuPress(
+  options: DropdownMenuPressOptions,
+): DropdownMenuPressReturn {
   const optionsRef = useRef(options);
   optionsRef.current = options;
   // The highlight, and the hover focus of the rows in this menu, follow the
   // last input, which this tracks for the menu's own document.
   useInteractionModalityTrackingFor(options.menuRef);
 
-  const gestureRef = useRef<MenuPressGesture<HTMLElement>>(IDLE_MENU_PRESS);
+  const gestureRef = useRef<MenuPressState<HTMLElement>>(IDLE_MENU_PRESS);
   const pointerIdRef = useRef<number | null>(null);
   const detachRef = useRef<(() => void) | null>(null);
   // `useLongPress` detects the held finger, as in ContextMenu, so the hold
@@ -374,8 +436,18 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
     autoscrollRef.current = null;
   }, [autoscroll]);
 
+  const litRowRef = useRef<HTMLElement | null>(null);
+  const heldMenuRef = useRef<HTMLElement | null>(null);
   const endGesture = useCallback(() => {
     longPressApiRef.current?.cancel();
+    if (litRowRef.current != null) {
+      clearMenuPressLit(litRowRef.current);
+      litRowRef.current = null;
+    }
+    if (heldMenuRef.current != null) {
+      releaseMenuPressPaint(heldMenuRef.current);
+      heldMenuRef.current = null;
+    }
     touchMovePreventerRef.current?.();
     touchMovePreventerRef.current = null;
     stopAutoscroll();
@@ -388,7 +460,34 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
 
   const highlight = useCallback(
     (row: HTMLElement | null) => {
+      // A held finger or pen marks the row it lights, for the row's pressed
+      // paint. A held mouse keeps the hover tint, as on a desktop.
+      const gesture = gestureRef.current;
+      const isHeld =
+        gesture.phase !== 'idle' && gesture.pointerType !== 'mouse';
+      const lit = isHeld ? row : null;
+      if (litRowRef.current !== lit) {
+        if (litRowRef.current != null) {
+          clearMenuPressLit(litRowRef.current);
+        }
+        litRowRef.current = lit;
+        if (lit != null) {
+          markMenuPressLit(lit);
+        }
+      }
       const {onHighlight, menuRef} = optionsRef.current;
+      // The row the press began on stays :active where a pointer hovers, so
+      // the menu holds every row but the lit one off that paint.
+      const held = isHeld ? menuRef.current : null;
+      if (heldMenuRef.current !== held) {
+        if (heldMenuRef.current != null) {
+          releaseMenuPressPaint(heldMenuRef.current);
+        }
+        heldMenuRef.current = held;
+        if (held != null) {
+          holdMenuPressPaint(held);
+        }
+      }
       if (onHighlight != null) {
         onHighlight(row);
         return;
@@ -449,13 +548,13 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
 
   // Declared before `step` so the mutual recursion through refs type-checks.
   const stepRef = useRef<
-    (event: MenuPressEvent<HTMLElement>, native?: PointerEvent) => void
+    (event: MenuPressInput<HTMLElement>, native?: PointerEvent) => void
   >(() => {});
 
   const applyEffect = useCallback(
     (
-      effect: MenuPressEffect<HTMLElement>,
-      gesture: MenuPressGesture<HTMLElement>,
+      effect: MenuPressOutcome<HTMLElement>,
+      gesture: MenuPressState<HTMLElement>,
       native: PointerEvent | undefined,
     ) => {
       const doc = getDocument();
@@ -511,8 +610,8 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
   );
 
   const step = useCallback(
-    (event: MenuPressEvent<HTMLElement>, native?: PointerEvent) => {
-      const result = menuPressStep(gestureRef.current, event);
+    (event: MenuPressInput<HTMLElement>, native?: PointerEvent) => {
+      const result = menuPressTransition(gestureRef.current, event);
       gestureRef.current = result.gesture;
       applyEffect(result.effect, result.gesture, native);
     },
@@ -619,6 +718,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
             row: point.row,
             isInMenu: point.isInMenu,
             time: Date.now(),
+            ...handoffPosition(
+              event,
+              optionsRef.current.touchModel === 'uikit',
+            ),
           },
           event,
         );
@@ -636,6 +739,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
             isInMenu: point.isInMenu,
             isOnTrigger: point.isOnTrigger,
             time: Date.now(),
+            ...handoffPosition(
+              event,
+              optionsRef.current.touchModel === 'uikit',
+            ),
           },
           event,
         );

package/src/hooks/useOverflow.ts

@@ -4,7 +4,8 @@
 
 /**
  * @file useOverflow.ts
- * @input Uses React useState, useCallback, useRef; useIsomorphicLayoutEffect
+ * @input Uses React useState, useCallback, useRef; react-dom flushSync;
+ *   useIsomorphicLayoutEffect
  * @output Exports useOverflow hook for measuring and managing horizontal overflow
  * @position Core hook; used by OverflowList and consumers for overflow patterns.
  *   Hidden copies of the children are measured, so nothing flickers. The
@@ -16,9 +17,10 @@
  */
 
 import {useState, useCallback, useRef} from 'react';
+import {flushSync} from 'react-dom';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 import {observeResize} from '../utils/sharedResizeObserver';
-import {computeOverflow} from './computeOverflow';
+import {computeOverflow, countRows} from './computeOverflow';
 import {useDevWarning} from './useDevWarning';
 
 export interface UseOverflowOptions {
@@ -85,6 +87,161 @@ export interface UseOverflowReturn {
   rowHeight: number;
 }
 
+// A measurement either applies its result at once or returns the update to
+// apply after the frame paints.
+type Measure = (timing: 'now' | 'beforePaint') => (() => void) | undefined;
+
+// Measurements that the resize observer reported in the current frame.
+const pendingMeasures = new Set<Measure>();
+
+/**
+ * Measures again for a resize the observer reported.
+ *
+ * The observer reports after layout and before paint. A state update here
+ * renders in a later task, after the frame paints. A microtask still runs
+ * before paint. It measures every reported list and renders the results once.
+ * An update that a measurement returns renders in a later task, after paint.
+ */
+function measureBeforePaint(measure: Measure): void {
+  if (pendingMeasures.size === 0) {
+    queueMicrotask(() => {
+      const measures = [...pendingMeasures];
+      pendingMeasures.clear();
+      const afterPaint: (() => void)[] = [];
+      // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the new visible set must render before the frame that reported the resize paints
+      flushSync(() => {
+        for (const run of measures) {
+          const deferred = run('beforePaint');
+          if (deferred) {
+            afterPaint.push(deferred);
+          }
+        }
+      });
+      for (const update of afterPaint) {
+        update();
+      }
+    });
+  }
+  pendingMeasures.add(measure);
+}
+
+/**
+ * The registration call runs while React commits the ref, before paint, so it
+ * measures at once.
+ */
+function observeForOverflow(element: Element, measure: Measure): () => void {
+  let isRegistering = true;
+  const unobserve = observeResize(element, () => {
+    if (isRegistering) {
+      measure('now');
+    } else {
+      measureBeforePaint(measure);
+    }
+  });
+  isRegistering = false;
+  return unobserve;
+}
+
+/** A visible set as the list renders it, sized from the measure copy. */
+interface RenderedSet {
+  widths: number[];
+  heights: number[];
+  /** The measured indicator, when the set collapses items. */
+  indicator: {width: number; height: number} | null;
+  indicatorFirst: boolean;
+}
+
+/**
+ * The rows a set fills at `availableWidth`, up to `maxRows`, or `null` when
+ * they are not known. The measured indicator holds every item, so the
+ * rendered one can be narrower. When the rows with and without it differ,
+ * the rows are not known.
+ */
+function rowsFilled(
+  set: RenderedSet,
+  gap: number,
+  availableWidth: number,
+  maxRows: number,
+): number | null {
+  const rowsWithout = Math.min(
+    countRows(set.widths, gap, availableWidth),
+    maxRows,
+  );
+  if (!set.indicator) {
+    return rowsWithout;
+  }
+  const widths = set.indicatorFirst
+    ? [set.indicator.width, ...set.widths]
+    : [...set.widths, set.indicator.width];
+  const rowsWith = Math.min(countRows(widths, gap, availableWidth), maxRows);
+  return rowsWith === rowsWithout ? rowsWith : null;
+}
+
+/**
+ * The list's height follows its tallest child and, in a multi-row list, the
+ * rows it fills.
+ */
+function canChangeListHeight(
+  now: RenderedSet,
+  next: RenderedSet,
+  gap: number,
+  availableWidth: number,
+  maxRows: number,
+): boolean {
+  const tallest = (set: RenderedSet) =>
+    Math.max(0, ...set.heights, set.indicator?.height ?? 0);
+  if (tallest(now) !== tallest(next)) {
+    return true;
+  }
+  if (maxRows <= 1) {
+    return false;
+  }
+  const rowsNow = rowsFilled(now, gap, availableWidth, maxRows);
+  const rowsNext = rowsFilled(next, gap, availableWidth, maxRows);
+  return rowsNow === null || rowsNext === null || rowsNow !== rowsNext;
+}
+
+/**
+ * Whether the observed element's size follows the list's items: a list in a
+ * flex item sized from its content, a shrink-to-fit box, or such an ancestor.
+ * A fold then changes an observed size, so it cannot render inside the
+ * observer step. Size containment drops the items' contribution to the
+ * list's inline size, so a size that moves under it follows the items. The
+ * probe reverts at once, before any observer or the frame can see it.
+ */
+function observedSizeFollowsItems(
+  list: HTMLElement,
+  observed: HTMLElement,
+): boolean {
+  const style = list.style as CSSStyleDeclaration | undefined;
+  if (style == null || typeof style.setProperty !== 'function') {
+    return false;
+  }
+  const hadStyleAttribute = list.hasAttribute('style');
+  const value = style.getPropertyValue('contain');
+  const priority = style.getPropertyPriority('contain');
+  const width = observed.offsetWidth;
+  const height = observed.offsetHeight;
+  style.setProperty('contain', 'inline-size', 'important');
+  const follows =
+    observed.offsetWidth !== width || observed.offsetHeight !== height;
+  if (value !== '') {
+    style.setProperty('contain', value, priority);
+  } else if (hadStyleAttribute) {
+    style.removeProperty('contain');
+  } else {
+    style.removeProperty('contain');
+    // Chromium writes the inline style back to the attribute lazily. Reading
+    // the attribute first stops the removal from leaving `style=""`.
+    void list.getAttribute('style');
+    list.removeAttribute('style');
+  }
+  // Lay out again now. A later observer in this delivery reads the current
+  // layout without updating it, so it would get the contained size.
+  void observed.offsetWidth;
+  return follows;
+}
+
 /**
  * Hook for managing horizontal overflow of a list of items.
  *
@@ -129,6 +286,9 @@ export function useOverflow(
   const [visibleCount, setVisibleCount] = useState(itemCount);
   const [rows, setRows] = useState(1);
   const [rowHeight, setRowHeight] = useState(0);
+  // The values last written to state. A measurement that matches them writes
+  // nothing, so a resize that changes nothing renders nothing.
+  const appliedRef = useRef({visibleCount: itemCount, rows: 1, rowHeight: 0});
   const containerElRef = useRef<HTMLElement | null>(null);
   const measureElRef = useRef<HTMLElement | null>(null);
   const observedElRef = useRef<HTMLElement | null>(null);
@@ -136,80 +296,148 @@ export function useOverflow(
   const unobserveContainerRef = useRef<(() => void) | null>(null);
   const unobserveMeasureRef = useRef<(() => void) | null>(null);
 
-  const calculate = useCallback(() => {
-    const container = containerElRef.current;
-    const measure = measureElRef.current;
-    if (!container || !measure) {
-      return;
-    }
+  const apply = useCallback(
+    (nextVisible: number, nextRows: number, nextRowHeight: number) => {
+      const applied = appliedRef.current;
+      if (applied.visibleCount !== nextVisible) {
+        applied.visibleCount = nextVisible;
+        setVisibleCount(nextVisible);
+      }
+      if (applied.rows !== nextRows) {
+        applied.rows = nextRows;
+        setRows(nextRows);
+      }
+      if (applied.rowHeight !== nextRowHeight) {
+        applied.rowHeight = nextRowHeight;
+        setRowHeight(nextRowHeight);
+      }
+    },
+    [],
+  );
 
-    let availableWidth: number;
+  const calculate: Measure = useCallback(
+    (timing = 'now') => {
+      const container = containerElRef.current;
+      const measure = measureElRef.current;
+      if (!container || !measure) {
+        return;
+      }
 
-    if (observeParent && container.parentElement) {
-      const parent = container.parentElement;
-      const parentStyle = getComputedStyle(parent);
-      availableWidth =
-        parent.clientWidth -
-        parseFloat(parentStyle.paddingLeft) -
-        parseFloat(parentStyle.paddingRight);
-    } else {
-      availableWidth = container.offsetWidth;
-    }
+      let availableWidth: number;
+
+      if (observeParent && container.parentElement) {
+        const parent = container.parentElement;
+        const parentStyle = getComputedStyle(parent);
+        availableWidth =
+          parent.clientWidth -
+          parseFloat(parentStyle.paddingLeft) -
+          parseFloat(parentStyle.paddingRight);
+      } else {
+        availableWidth = container.offsetWidth;
+      }
 
-    const allChildren = Array.from(measure.children) as HTMLElement[];
-
-    // The measurement container holds itemCount items, plus optionally
-    // an overflow indicator as the last child.
-    const hasIndicator = allChildren.length > itemCount;
-    const children = hasIndicator
-      ? allChildren.slice(0, itemCount)
-      : allChildren;
-    const indicatorWidth = hasIndicator
-      ? allChildren[allChildren.length - 1].offsetWidth
-      : 0;
-
-    if (children.length === 0) {
-      // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
-      setVisibleCount(0);
-      // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
-      setRows(0);
-      return;
-    }
+      const allChildren = Array.from(measure.children) as HTMLElement[];
+
+      // The measurement container holds itemCount items, plus optionally
+      // an overflow indicator as the last child.
+      const hasIndicator = allChildren.length > itemCount;
+      const children = hasIndicator
+        ? allChildren.slice(0, itemCount)
+        : allChildren;
+      const indicatorWidth = hasIndicator
+        ? allChildren[allChildren.length - 1].offsetWidth
+        : 0;
 
-    const widths = children.map(child => child.offsetWidth);
-    const measuredRowHeight = children.reduce(
-      (max, child) => Math.max(max, child.offsetHeight || 0),
-      0,
-    );
+      if (children.length === 0) {
+        apply(0, 0, appliedRef.current.rowHeight);
+        return;
+      }
 
-    const {visibleCount: nextVisible, rows: nextRows} = computeOverflow({
-      widths,
+      const widths = children.map(child => child.offsetWidth);
+      const measuredRowHeight = children.reduce(
+        (max, child) => Math.max(max, child.offsetHeight || 0),
+        0,
+      );
+
+      const {visibleCount: nextVisible, rows: nextRows} = computeOverflow({
+        widths,
+        gap,
+        availableWidth,
+        indicatorWidth,
+        minVisibleItems,
+        maxVisibleItems,
+        maxRows,
+        collapseFrom,
+      });
+
+      // Folding to a new list height inside the resize step makes Chromium
+      // report a loop error. That update renders after paint. The measure copy
+      // sizes both sets, a plain-text indicator included.
+      if (timing === 'beforePaint') {
+        const indicator = hasIndicator
+          ? allChildren[allChildren.length - 1]
+          : null;
+        const renderedSet = (count: number): RenderedSet => {
+          const shown =
+            collapseFrom === 'end'
+              ? children.slice(0, count)
+              : children.slice(children.length - count);
+          return {
+            widths: shown.map(child => child.offsetWidth),
+            heights: shown.map(child => child.offsetHeight || 0),
+            indicator:
+              indicator && count < itemCount
+                ? {width: indicatorWidth, height: indicator.offsetHeight || 0}
+                : null,
+            indicatorFirst: collapseFrom === 'start',
+          };
+        };
+        // Under observeParent the list fills its parent's width only while
+        // items are collapsed. A fold that shows or hides the indicator
+        // changes that width, which can change the observed parent's height
+        // when a sibling wraps.
+        const changesParentFill =
+          observeParent &&
+          appliedRef.current.visibleCount < itemCount !==
+            nextVisible < itemCount;
+        // A multi-row list's max height follows the measured row height.
+        const changesRowHeight =
+          (maxRows ?? 1) > 1 &&
+          measuredRowHeight !== appliedRef.current.rowHeight;
+        const observed =
+          observeParent && container.parentElement
+            ? container.parentElement
+            : container;
+        if (
+          changesParentFill ||
+          changesRowHeight ||
+          (nextVisible !== appliedRef.current.visibleCount &&
+            observedSizeFollowsItems(container, observed)) ||
+          canChangeListHeight(
+            renderedSet(appliedRef.current.visibleCount),
+            renderedSet(nextVisible),
+            gap,
+            availableWidth,
+            maxRows ?? 1,
+          )
+        ) {
+          return () => apply(nextVisible, nextRows, measuredRowHeight);
+        }
+      }
+      apply(nextVisible, nextRows, measuredRowHeight);
+      return undefined;
+    },
+    [
+      itemCount,
       gap,
-      availableWidth,
-      indicatorWidth,
       minVisibleItems,
       maxVisibleItems,
       maxRows,
       collapseFrom,
-    });
-
-    // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
-    setVisibleCount(nextVisible);
-    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
-    setRows(prev => (prev === nextRows ? prev : nextRows));
-    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
-    setRowHeight(prev =>
-      prev === measuredRowHeight ? prev : measuredRowHeight,
-    );
-  }, [
-    itemCount,
-    gap,
-    minVisibleItems,
-    maxVisibleItems,
-    maxRows,
-    collapseFrom,
-    observeParent,
-  ]);
+      observeParent,
+      apply,
+    ],
+  );
 
   const containerRef = useCallback(
     (el: HTMLElement | null) => {
@@ -223,9 +451,7 @@ export function useOverflow(
       if (el) {
         const target =
           observeParent && el.parentElement ? el.parentElement : el;
-        unobserveContainerRef.current = observeResize(target, () => {
-          calculate();
-        });
+        unobserveContainerRef.current = observeForOverflow(target, calculate);
         observedElRef.current = target;
       }
     },
@@ -243,9 +469,7 @@ export function useOverflow(
         return;
       }
 
-      unobserveMeasureRef.current = observeResize(el, () => {
-        calculate();
-      });
+      unobserveMeasureRef.current = observeForOverflow(el, calculate);
       observedMeasureElRef.current = el;
     },
     [calculate],
@@ -254,7 +478,7 @@ export function useOverflow(
   // Syncs the visible count with the rendered layout. It measures again after
   // the items change.
   useIsomorphicLayoutEffect(() => {
-    calculate();
+    calculate('now');
   }, [calculate]);
 
   const hasOverflow = visibleCount < itemCount;

package/src/hooks/usePressFeedback.doc.mjs

@@ -20,12 +20,12 @@ export const docs = {
       name: 'pressableProps',
       type: "{'data-astryx-pressable': ''}",
       description:
-        "The marker attribute to spread on the element that paints the press. Compose one of `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same element — `backgroundColor` or `backgroundImage` for a surface whose hover and press are the system's overlays, `pressedBackgroundColor` for one whose hover is its own — and it paints the pressed token at the press's strength on the first frame of a believed press and fades it over the release, keeping `:active` for a mouse on a desktop. On a phone or tablet, where the stylesheet drops `:active`, the controller also paints a mouse, trackpad or Space-key press: at once, held while the button or key is down, faded at the release. A press is themed through `--color-overlay-pressed`.",
+        "The marker attribute to spread on the element that paints the press. Compose one of `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same element — `backgroundColor` or `backgroundImage` for a surface whose hover and press are the system's overlays, `pressedBackgroundColor` for one whose hover is its own — and it paints the pressed token on the first frame of a press and fades it over the release, keeping `:active` for a mouse on a desktop. On a phone or tablet, where the stylesheet drops `:active`, the controller also paints a mouse, trackpad or Space-key press: at once, held while the button or key is down, faded at the release. A press is themed through `--color-overlay-pressed`.",
     },
   ],
   usage: {
     description:
-      'The touch press model every Astryx pressable uses, for a local component that paints its own press. Under a finger, CSS `:active` paints on the touch itself and can outlive the start of a scroll; the press model instead waits 150 ms before believing a press, cancels it the moment the finger travels 10 px or a scroll claims the gesture, never brings it back inside that gesture, answers a quick tap at the lift, and fades the release over 200 ms — the clocks a native list uses. One document-level controller does this for every marked element (installed by the first pressable to mount, removed by the last to unmount), so calling the hook adds no listener or state to your element. On a desktop a mouse press is still your `:active` rule: keep it, and drop it under `@media (pointer: coarse)` the way the built-in components do. That query reads the primary pointer, so on a phone or tablet it also drops `:active` for a connected mouse, trackpad or keyboard; the controller paints those presses there (at once, faded at the release), so nothing goes unanswered.',
+      'The touch press model every Astryx pressable uses, for a local component that paints its own press. Under a finger, CSS `:active` paints on the touch itself and can outlive the start of a scroll; the press model instead tracks the touch the way UIKit tracks a control: it highlights as the finger lands (after the content-touch delay inside a scroller, where a flick paints nothing), a quick tap answers at the lift, and a scroll that takes the touch cancels it with no fade. One document-level controller does this for every marked element (installed by the first pressable to mount, removed by the last to unmount), so calling the hook adds no listener or state to your element. On a desktop a mouse press is still your `:active` rule: keep it, and drop it under `@media (pointer: coarse)` the way the built-in components do. That query reads the primary pointer, so on a phone or tablet it also drops `:active` for a connected mouse, trackpad or keyboard; the controller paints those presses there (at once, faded at the release), so nothing goes unanswered.',
     bestPractices: [
       {
         guidance: true,
@@ -58,7 +58,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Marks an element as a pressable surface of the touch press model (150 ms onset, 10 px slop, cancel on scroll, tap answers at lift, 200 ms fade) and installs the shared document controller; on a coarse primary pointer it also paints mouse, trackpad and Space-key presses at once. Returns the data-astryx-pressable marker to spread; compose one of interactionOverlayStyles on the same element to paint.',
+    'Marks an element as a pressable surface of the touch press model, tracked like a UIKit control (highlight as the finger lands, 150 ms inside a scroller, fade at the lift), and installs the shared document controller; on a coarse primary pointer it also paints mouse, trackpad and Space-key presses at once. Returns the data-astryx-pressable marker to spread; compose one of interactionOverlayStyles on the same element to paint.',
   paramDescriptions: {},
   returnDescriptions: {
     pressableProps: