@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/gestures/touchAction.ts

@@ -0,0 +1,191 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchAction.ts
+ * @input The recognizers attached to one element
+ * @output Exports deriveTouchAction (the element's `touch-action`),
+ *   gestureHostStyle (the inline style a host sets for its recognizers),
+ *   intersectTouchAction (what both a derived and a caller's value allow) and
+ *   holdSelectionStyle (the selection and callout lock for one held press)
+ * @position Browser negotiation of packages/core/src/gestures, pure so a
+ *   server render can emit the same style the client would set
+ *
+ * `touch-action` is decided when the finger lands and cannot change during
+ * the gesture, so it must say up front what the browser may still do: the
+ * intersection of what every recognizer on the element leaves it.
+ *
+ * - A tap or long press only removes double-tap zoom (`manipulation`): no
+ *   300 ms click delay, scrolling and pinch-zoom untouched.
+ * - A one-axis pan or swipe gives the browser the other axis.
+ * - A pan that coordinates with native scrolling (`scrollEdge`) keeps both
+ *   axes: who gets the drag is decided once, when it begins, and a drag the
+ *   browser began scrolling stays the browser's to the lift (`spec:AST-094`
+ *   FR14).
+ * - `pinch-zoom` stays in every value unless a pinch recognizer is attached,
+ *   so the page stays zoomable (WCAG 1.4.4).
+ *
+ * WebKit pans a drag with any vertical component even under `pan-y`, so the
+ * value alone does not protect a horizontal pan there: the host also cancels
+ * `touchmove` while a recognizer owns the touch (see GestureHost.ts).
+ */
+
+import type {GestureRecognizer, NativeTouchBehavior} from './GestureRecognizer';
+
+/** The intersection of what each touch recognizer leaves the browser. */
+export function combinedNativeBehavior(
+  recognizers: ReadonlyArray<GestureRecognizer>,
+): NativeTouchBehavior {
+  let panX = true;
+  let panY = true;
+  let pinchZoom = true;
+  let doubleTapZoom = true;
+  for (const recognizer of recognizers) {
+    if (!recognizer.acceptsTouchInput) {
+      continue;
+    }
+    const behavior = recognizer.nativeTouchBehavior;
+    panX &&= behavior.panX;
+    panY &&= behavior.panY;
+    pinchZoom &&= behavior.pinchZoom;
+    doubleTapZoom &&= behavior.doubleTapZoom;
+  }
+  return {panX, panY, pinchZoom, doubleTapZoom};
+}
+
+/** The `touch-action` value for a set of recognizers, or null for none needed. */
+export function deriveTouchAction(
+  recognizers: ReadonlyArray<GestureRecognizer>,
+): string | null {
+  const behavior = combinedNativeBehavior(recognizers);
+  if (
+    behavior.panX &&
+    behavior.panY &&
+    behavior.pinchZoom &&
+    behavior.doubleTapZoom
+  ) {
+    return null;
+  }
+  if (behavior.panX && behavior.panY && behavior.pinchZoom) {
+    return 'manipulation';
+  }
+  const tokens: string[] = [];
+  if (behavior.panX) {
+    tokens.push('pan-x');
+  }
+  if (behavior.panY) {
+    tokens.push('pan-y');
+  }
+  if (behavior.pinchZoom) {
+    tokens.push('pinch-zoom');
+  }
+  return tokens.length === 0 ? 'none' : tokens.join(' ');
+}
+
+export interface GestureHostStyle {
+  touchAction?: string;
+  WebkitTouchCallout?: string;
+  WebkitUserSelect?: string;
+  userSelect?: string;
+}
+
+/**
+ * The style a host sets for these recognizers while they are attached: the
+ * `touch-action`. Text selection is not locked here: a mouse, a keyboard and
+ * assistive technology keep selecting as they do today (spec:AST-017 FR59,
+ * spec:AST-094 FR41).
+ */
+export function gestureHostStyle(
+  recognizers: ReadonlyArray<GestureRecognizer>,
+): GestureHostStyle {
+  const style: GestureHostStyle = {};
+  const touchAction = deriveTouchAction(recognizers);
+  if (touchAction != null) {
+    style.touchAction = touchAction;
+  }
+  return style;
+}
+
+/** What a `touch-action` value lets the browser do, as tokens. */
+const ALL_PANS = [
+  'pan-left',
+  'pan-right',
+  'pan-up',
+  'pan-down',
+  'pinch-zoom',
+] as const;
+
+function touchActionTokens(value: string): Set<string> {
+  const parts = value
+    .trim()
+    .split(/\s+/)
+    .filter(part => part !== '');
+  const tokens = new Set<string>();
+  if (parts.length === 0) {
+    parts.push('auto');
+  }
+  for (const part of parts) {
+    if (part === 'auto') {
+      ALL_PANS.forEach(token => tokens.add(token));
+      tokens.add('double-tap-zoom');
+    } else if (part === 'manipulation') {
+      ALL_PANS.forEach(token => tokens.add(token));
+    } else if (part === 'pan-x') {
+      tokens.add('pan-left').add('pan-right');
+    } else if (part === 'pan-y') {
+      tokens.add('pan-up').add('pan-down');
+    } else if ((ALL_PANS as ReadonlyArray<string>).includes(part)) {
+      tokens.add(part);
+    }
+  }
+  return tokens;
+}
+
+/**
+ * The `touch-action` that allows only what both values allow: the host's
+ * derived value never overrides a caller's narrower one.
+ */
+export function intersectTouchAction(derived: string, caller: string): string {
+  const own = touchActionTokens(caller);
+  const both = new Set(
+    [...touchActionTokens(derived)].filter(token => own.has(token)),
+  );
+  if (ALL_PANS.every(token => both.has(token))) {
+    return both.has('double-tap-zoom') ? 'auto' : 'manipulation';
+  }
+  const parts: string[] = [];
+  for (const [axis, start, end] of [
+    ['pan-x', 'pan-left', 'pan-right'],
+    ['pan-y', 'pan-up', 'pan-down'],
+  ] as const) {
+    if (both.has(start) && both.has(end)) {
+      parts.push(axis);
+    } else if (both.has(start)) {
+      parts.push(start);
+    } else if (both.has(end)) {
+      parts.push(end);
+    }
+  }
+  if (both.has('pinch-zoom')) {
+    parts.push('pinch-zoom');
+  }
+  return parts.length === 0 ? 'none' : parts.join(' ');
+}
+
+/**
+ * The lock a host applies for one press only, from touch-down to the lift or
+ * a cancel, on an element whose hold does something (a long press): no iOS
+ * callout and no text-selection start under the held finger, as a
+ * long-pressed row in UIKit selects no text (spec:AST-094 FR41). Null where
+ * the hold does nothing, so a long press there selects natively.
+ */
+export function holdSelectionStyle(
+  recognizers: ReadonlyArray<GestureRecognizer>,
+): GestureHostStyle | null {
+  const holds = recognizers.some(
+    recognizer =>
+      recognizer.kind === 'longPress' && recognizer.acceptsTouchInput,
+  );
+  return holds
+    ? {WebkitTouchCallout: 'none', WebkitUserSelect: 'none', userSelect: 'none'}
+    : null;
+}

package/src/gestures/touchActionRule.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchActionRule.ts
+ * @input An element and the touch-action its recognizers derive
+ * @output Exports markTouchAction and unmarkTouchAction: the element carries
+ *   the derived value in TOUCH_ACTION_ATTRIBUTE, and its document or shadow
+ *   root holds one zero-specificity rule per value in the first cascade
+ *   layer (`reset`), so any author rule, in any layer or none, or inline
+ *   value outranks the host's (`spec:AST-094` FR18, DEC-8); a root's rules
+ *   go with its last marked element (FR24)
+ * @position The gesture host's touch-action writer (GestureHost.ts)
+ *
+ * The mark is set as a recognizer attaches, so a subtree that mounts with
+ * it is styled once with its touch-action: a value written after that first
+ * styling restyles every descendant (each one's effective touch-action
+ * changes). Until the host reads the element's own value, the value in
+ * force is the author's where the author sets one, and the derived value
+ * elsewhere: never wider than the author's.
+ *
+ * SYNC: When modified, update GestureHost.ts.
+ */
+
+/** The attribute that carries the host's derived touch-action. */
+export const TOUCH_ACTION_ATTRIBUTE = 'data-astryx-touch-action';
+
+/**
+ * The cascade layer the rules sit in: the first in the order every package
+ * stylesheet declares (`spec:AST-080` FR3), so an author rule in any later
+ * layer, or in none, outranks them. Unlayered, they would outrank every
+ * layered author rule.
+ */
+const RULE_LAYER = 'reset';
+
+type RuleRoot = Document | ShadowRoot;
+
+/**
+ * Per document or shadow root: the values it has a rule for, their rules'
+ * text, where that text goes (an adopted sheet, or a style element where
+ * constructable sheets are missing), and the elements marked there. The
+ * rules go with the root's last marked element (`spec:AST-094` FR24).
+ */
+const sheets = new WeakMap<
+  RuleRoot,
+  {
+    readonly values: Set<string>;
+    readonly marked: Set<Element>;
+    css: string;
+    write(css: string): void;
+    remove(): void;
+  }
+>();
+
+/** Where each marked element's rule lives, for its unmark after it leaves. */
+const markedRoots = new WeakMap<Element, RuleRoot>();
+
+function sheetOf(root: RuleRoot) {
+  let entry = sheets.get(root);
+  if (entry == null) {
+    const doc = root.nodeType === 9 ? (root as Document) : root.ownerDocument;
+    let write: ((css: string) => void) | undefined;
+    let remove: (() => void) | undefined;
+    // A constructable sheet where the engine has one; a style element only
+    // where it has none, so any other error from a sheet is not hidden.
+    const Sheet = doc?.defaultView?.CSSStyleSheet;
+    if (
+      typeof Sheet === 'function' &&
+      'replaceSync' in Sheet.prototype &&
+      'adoptedStyleSheets' in root
+    ) {
+      const sheet = new Sheet();
+      root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+      write = css => sheet.replaceSync(css);
+      remove = () => {
+        root.adoptedStyleSheets = root.adoptedStyleSheets.filter(
+          adopted => adopted !== sheet,
+        );
+      };
+    } else {
+      const style = doc?.createElement('style');
+      const parent =
+        root.nodeType === 9 ? (doc?.head ?? doc?.documentElement) : root;
+      if (style != null && parent != null) {
+        parent.append(style);
+        write = css => {
+          style.textContent = css;
+        };
+        remove = () => style.remove();
+      }
+    }
+    if (write == null || remove == null) {
+      return null;
+    }
+    entry = {values: new Set(), marked: new Set(), css: '', write, remove};
+    sheets.set(root, entry);
+  }
+  return entry;
+}
+
+/**
+ * Give `element` the derived touch-action under a rule any author rule
+ * outranks. Returns false where no rule can hold it (a detached element):
+ * the caller writes nothing until the element is in a document.
+ */
+export function markTouchAction(element: Element, value: string): boolean {
+  const root = element.getRootNode() as RuleRoot;
+  const entry =
+    element.isConnected && (root.nodeType === 9 || 'host' in root)
+      ? sheetOf(root)
+      : null;
+  if (entry == null) {
+    return false;
+  }
+  if (!entry.values.has(value)) {
+    entry.values.add(value);
+    entry.css += `:where([${TOUCH_ACTION_ATTRIBUTE}="${value}"]){touch-action:${value}}`;
+    entry.write(`@layer ${RULE_LAYER}{${entry.css}}`);
+  }
+  if (element.getAttribute(TOUCH_ACTION_ATTRIBUTE) !== value) {
+    element.setAttribute(TOUCH_ACTION_ATTRIBUTE, value);
+  }
+  const previous = markedRoots.get(element);
+  if (previous != null && previous !== root) {
+    // Moved to another root: the old one lets it go.
+    releaseMark(element, previous);
+  }
+  entry.marked.add(element);
+  markedRoots.set(element, root);
+  return true;
+}
+
+/** `root` no longer holds `element`'s mark; its last mark takes the rules. */
+function releaseMark(element: Element, root: RuleRoot): void {
+  const entry = sheets.get(root);
+  if (entry == null) {
+    return;
+  }
+  entry.marked.delete(element);
+  if (entry.marked.size === 0) {
+    entry.remove();
+    sheets.delete(root);
+  }
+}
+
+/**
+ * Remove the host's mark; the element's own touch-action stands. The last
+ * mark in a document or shadow root takes its rules with it.
+ */
+export function unmarkTouchAction(element: Element): void {
+  element.removeAttribute(TOUCH_ACTION_ATTRIBUTE);
+  const root = markedRoots.get(element);
+  if (root == null) {
+    return;
+  }
+  markedRoots.delete(element);
+  releaseMark(element, root);
+}

package/src/gestures/types.ts

@@ -46,13 +46,6 @@ export interface NativeScrollProbe {
    * lets the browser pan that axis).
    */
   canScroll(dx: number, dy: number): boolean;
-  /**
-   * How much further (px) the scroller that would move for a finger moving
-   * by (dx, dy) can scroll before it reaches its edge; 0 when none would.
-   * Lets a reader place the point where the content runs out between two
-   * samples instead of at the next one.
-   */
-  distanceToEdge?(dx: number, dy: number): number;
   /** Whether any element under the touch can scroll natively at all. */
   readonly isInsideScroller: boolean;
   /**
@@ -127,6 +120,17 @@ export interface GestureEventContext {
 export interface GestureEnvironment {
   viewportSize(): {readonly width: number; readonly height: number};
   isRtl(view: unknown): boolean;
+  /**
+   * The box of a recognizer's view in viewport coordinates, or null when it
+   * has none to measure. A screen-edge pan reads it to tell a view within
+   * its edge band from any other.
+   */
+  viewRect?(view: unknown): {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  } | null;
 }
 
 export const DEFAULT_ENVIRONMENT: GestureEnvironment = {
@@ -136,8 +140,18 @@ export const DEFAULT_ENVIRONMENT: GestureEnvironment = {
     }
     return {width: window.innerWidth, height: window.innerHeight};
   },
-  isRtl() {
-    return false;
+  isRtl(view) {
+    if (typeof window === 'undefined' || !(view instanceof Element)) {
+      return false;
+    }
+    return window.getComputedStyle(view).direction === 'rtl';
+  },
+  viewRect(view) {
+    if (typeof Element === 'undefined' || !(view instanceof Element)) {
+      return null;
+    }
+    const {left, top, width, height} = view.getBoundingClientRect();
+    return {left, top, width, height};
   },
 };
 
@@ -158,4 +172,11 @@ export interface TouchConsumer {
    * (attached above this consumer) from beginning for a touch on it.
    */
   allowsAncestorRecognizer?(recognizer: unknown): boolean;
+  /**
+   * Whether the consumer takes touches now (a disabled control does not).
+   * The host listens only while something enabled is attached
+   * (`spec:AST-094` FR24); after this changes, call `host.update(element)`.
+   * @default true
+   */
+  isEnabled?(): boolean;
 }