@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/utils/touchHitArea.stylex.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchHitArea.stylex.ts
+ * @input Uses StyleX and the insets that utils/hitArea.ts writes on a host
+ * @output Exports `touchHitAreaStyles.layer`, a host's invisible hit band
+ *   under a coarse pointer
+ * @position Internal styling utility for CheckboxInput, RadioListItem, List
+ *   rows and InfoTip. Each keeps its insets live with `useTouchHitArea`
+ *   (utils/touchHitArea.ts).
+ *
+ * The band is the host's `::after`, grown past each edge by the measured
+ * inset. A clip path cuts out the host's box, so its content keeps its taps.
+ * A tap on the band lands on the host. SYNC: hitArea.ts HIT_INSET_PROPERTIES,
+ * touchHitArea.ts and touchHitArea.test.tsx.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+// StyleX reads these at build time, so they are spelled out.
+const TOUCH = '@media (pointer: coarse)';
+// The insets are measured in the viewport, so the sides are physical.
+const TOP = 'var(--astryx-hit-inset-top, 0px)';
+const RIGHT = 'var(--astryx-hit-inset-right, 0px)';
+const BOTTOM = 'var(--astryx-hit-inset-bottom, 0px)';
+const LEFT = 'var(--astryx-hit-inset-left, 0px)';
+// The insets start at the host's border box, but the band's offsets start at
+// its padding box. So a host that draws a border declares its width on that
+// side, 0 by default. It declares it on its own `::after`, so content inside
+// the host never inherits it.
+const BORDER_TOP = 'var(--_hit-border-top, 0px)';
+const BORDER_RIGHT = 'var(--_hit-border-right, 0px)';
+const BORDER_BOTTOM = 'var(--_hit-border-bottom, 0px)';
+const BORDER_LEFT = 'var(--_hit-border-left, 0px)';
+
+// The host is the band's containing block, so a host that is not positioned
+// sets `position: relative`. The band has no z-index of its own. Inside a
+// List, which isolates its rows, ListItem raises it. Under a finger the host's
+// `::after` is this band, so decorate the host with a child.
+export const touchHitAreaStyles = stylex.create({
+  layer: {
+    '::after': {
+      content: {default: null, [TOUCH]: '""'},
+      position: {default: null, [TOUCH]: 'absolute'},
+      inset: {
+        default: null,
+        [TOUCH]: `calc((${TOP} + ${BORDER_TOP}) * -1) calc((${RIGHT} + ${BORDER_RIGHT}) * -1) calc((${BOTTOM} + ${BORDER_BOTTOM}) * -1) calc((${LEFT} + ${BORDER_LEFT}) * -1)`,
+      },
+      // The outer rectangle, then the host's box as an even-odd hole.
+      clipPath: {
+        default: null,
+        [TOUCH]: `polygon(evenodd, 0 0, 100% 0, 100% 100%, 0 100%, 0 0, ${LEFT} ${TOP}, calc(100% - ${RIGHT}) ${TOP}, calc(100% - ${RIGHT}) calc(100% - ${BOTTOM}), ${LEFT} calc(100% - ${BOTTOM}), ${LEFT} ${TOP})`,
+      },
+    },
+  },
+});

package/src/utils/touchHitArea.ts

@@ -0,0 +1,177 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file touchHitArea.ts
+ * @input Whether an element takes taps, the shared touch hit area
+ *   (utils/hitArea.ts) and the Web Animations around the element
+ * @output `useTouchHitArea`, a callback ref that keeps an element's hit insets
+ *   live for its invisible layer (`touchHitAreaStyles.layer`)
+ * @position Core-internal hook for the coarse-only 44 px target. List rows,
+ *   InfoTip, CheckboxInput and RadioListItem use it, and so can any control
+ *   whose target grows under a finger without growing its box.
+ *
+ * SYNC: When modified, update utils/touchHitArea.stylex.ts and
+ * touchHitArea.test.tsx.
+ */
+
+import {useCallback, type RefCallback} from 'react';
+import {
+  MIN_TOUCH_TARGET,
+  NO_HIT_INSETS,
+  watchHitArea,
+  writeHitInsets,
+} from './hitArea';
+
+/**
+ * The finite animations running or held in the element's parent, the element
+ * included: a row's own motion and its neighbors'. An endless one (a spinner)
+ * moves nothing that comes to rest, so it holds nothing.
+ */
+function settlingAnimations(element: HTMLElement): Animation[] {
+  const scope = element.parentElement ?? element;
+  if (typeof scope.getAnimations !== 'function') {
+    return [];
+  }
+  return scope.getAnimations({subtree: true}).filter(animation => {
+    if (animation.playState !== 'running' && animation.playState !== 'paused') {
+      return false;
+    }
+    const end = animation.effect?.getComputedTiming().endTime;
+    return typeof end === 'number' && Number.isFinite(end);
+  });
+}
+
+/**
+ * Watches `element` and takes its insets only at rest. Returns the stop.
+ *
+ * Under a coarse primary pointer, the shared utility measures how far the
+ * element's hit target may grow without reaching a neighbor's half of the
+ * gap. This writes those insets on the element, where its layer reads them.
+ * Under a fine pointer the shared utility starts no observer.
+ *
+ * Elements move by transform: a list row in an update's slide, a swipe, or
+ * neighbors that slide past. The shared measurement reads them as they stand
+ * in one frame. So a measurement that arrives while the parent has a finite
+ * animation running or held is dropped. When those animations end, the
+ * element is watched again. The insets are then taken at rest, and no frame
+ * of a compositor-only motion lays out or paints for them.
+ */
+function watchAtRest(element: HTMLElement, minSize: number): () => void {
+  let stopWatch = (): void => {};
+  let isStopped = false;
+  let isWaiting = false;
+  let hasWritten = false;
+  // A stopped watch clears the insets it wrote. A fresh watch skips a
+  // measurement equal to its start, zero, so old insets would otherwise stay.
+  // A watch that wrote nothing, as under a mouse, writes nothing.
+  const stop = (): void => {
+    stopWatch();
+    if (hasWritten) {
+      hasWritten = false;
+      writeHitInsets(element, NO_HIT_INSETS);
+    }
+  };
+  const watch = (): void => {
+    stopWatch = watchHitArea(
+      element,
+      insets => {
+        const moving = settlingAnimations(element);
+        if (moving.length === 0) {
+          hasWritten = true;
+          writeHitInsets(element, insets);
+          return;
+        }
+        if (isWaiting) {
+          return;
+        }
+        isWaiting = true;
+        void Promise.allSettled(
+          moving.map(async animation => animation.finished),
+        ).then(() => {
+          isWaiting = false;
+          if (!isStopped) {
+            stop();
+            watch();
+          }
+        });
+      },
+      // The layer is the host's own `::after`, so a touch on the host's
+      // content is the host's, even where that content paints past its box.
+      {minSize, ownsDescendantTouches: true},
+    );
+  };
+  watch();
+  return () => {
+    isStopped = true;
+    stop();
+  };
+}
+
+/** The watch on an element, and how many attached refs hold it. */
+interface HeldWatch {
+  readonly stop: () => void;
+  holders: number;
+}
+
+const heldWatches = new WeakMap<HTMLElement, HeldWatch>();
+
+/**
+ * Holds the element's watch, and starts it on the first hold. Returns the
+ * release. A ref that changes, such as a merge with a caller's inline ref,
+ * detaches and attaches again in one commit. So the last release waits a
+ * microtask, and an attach in between keeps the watch and its insets.
+ */
+function holdWatch(element: HTMLElement): () => void {
+  let held = heldWatches.get(element);
+  if (held == null) {
+    held = {stop: watchAtRest(element, MIN_TOUCH_TARGET), holders: 0};
+    heldWatches.set(element, held);
+  }
+  held.holders += 1;
+  const entry = held;
+  let isReleased = false;
+  return () => {
+    if (isReleased) {
+      return;
+    }
+    isReleased = true;
+    entry.holders -= 1;
+    queueMicrotask(() => {
+      if (entry.holders === 0 && heldWatches.get(element) === entry) {
+        heldWatches.delete(element);
+        entry.stop();
+      }
+    });
+  };
+}
+
+/**
+ * A callback ref that keeps its element's hit insets live while `enabled`:
+ * the element takes taps, so it is interactive and not disabled or read-only.
+ * Merge it into the element's ref, and pair it with `touchHitAreaStyles.layer`
+ * on the same element. The watch lasts while the element is attached, so a
+ * replaced element starts its own. A re-render that hands the same element a
+ * new merged ref keeps its watch.
+ *
+ * @example
+ * ```
+ * const hitAreaRef = useTouchHitArea(isInteractive && !isDisabled);
+ * <li ref={hitAreaRef} {...stylex.props(isInteractive && touchHitAreaStyles.layer)} />
+ * ```
+ */
+export function useTouchHitArea(enabled: boolean): RefCallback<HTMLElement> {
+  // Syncs with an external system: the shared touch hit area
+  // (utils/hitArea.ts) measures the element against its neighbors and writes
+  // its insets on it. The ref's cleanup stops the watch.
+  return useCallback(
+    (element: HTMLElement | null) => {
+      if (!enabled || element == null) {
+        return undefined;
+      }
+      return holdWatch(element);
+    },
+    [enabled],
+  );
+}

package/src/utils/triggerFocus.ts

@@ -37,6 +37,22 @@ export function isFocusableTrigger(element: HTMLElement): boolean {
 export function isFocusForTrigger(
   event: Event,
   mode: TriggerFocusMode,
+): boolean {
+  return isFocusOnTrigger(
+    event.target,
+    event.currentTarget as HTMLElement | null,
+    mode,
+  );
+}
+
+/**
+ * `isFocusForTrigger` for focus already on `target`, inside `trigger`: the
+ * same rule, read when a trigger attaches with focus inside it.
+ */
+export function isFocusOnTrigger(
+  target: EventTarget | null,
+  trigger: HTMLElement | null,
+  mode: TriggerFocusMode,
 ): boolean {
   if (mode === 'always') {
     return true;
@@ -44,10 +60,7 @@ export function isFocusForTrigger(
   if (mode === 'never') {
     return false;
   }
-  const trigger = event.currentTarget as HTMLElement | null;
-  return (
-    trigger != null && (event.target === trigger || isFocusableTrigger(trigger))
-  );
+  return trigger != null && (target === trigger || isFocusableTrigger(trigger));
 }
 
 /** Remembers whether a trigger's current focus counted when it arrived. */