@astryxdesign/core 0.7.7-canary.4a8a76e → 0.7.7-canary.4e495ec

package/src/utils/browserClickWait.ts

@@ -0,0 +1,133 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file browserClickWait.ts
+ * @input An element a tap's lift released on, and the control that acts on
+ *   its click
+ * @output BROWSER_CLICK_WAIT_MS, awaitBrowserClick, clickForLift and
+ *   clickAndReport
+ * @position The one wait for the browser's click after a tap, shared by
+ *   Switch/useSwitchTouch.ts and SegmentedControl/useSegmentedTouchTracking.ts.
+ *   It swallows nothing: utils/clickGuard.ts is the one guard for a late click.
+ *
+ * SYNC: When modified, update browserClickWait.test.ts.
+ */
+
+import {armClickGuard, withoutClickGuard} from './clickGuard';
+import {subscribeInput} from './inputStream';
+
+/**
+ * How long a tap's lift waits for the browser's own click, ms. The browser
+ * sends that click with the lift when the page has no double-tap delay. The
+ * wait runs out for a lift that the browser does not count as a click, such
+ * as a hold. It also runs out when a busy main thread holds the click back.
+ */
+export const BROWSER_CLICK_WAIT_MS = 300;
+
+/** What a control does when the browser's click comes, or does not. */
+export interface BrowserClickWaitHandlers {
+  /** The browser's click ran its handlers. `isCancelled`: one cancelled it. */
+  readonly onClicked: (isCancelled: boolean) => void;
+  /** No browser click came in time. */
+  readonly onNoClick: () => void;
+}
+
+/**
+ * Waits for the browser's own click inside `target` after a tap's lift. That
+ * click is the activation: `onClicked` runs once its handlers have run. With
+ * no click in time, `onNoClick` runs. The returned call ends the wait at once
+ * and leaves no listener or timer behind.
+ */
+export function awaitBrowserClick(
+  target: Element,
+  {onClicked, onNoClick}: BrowserClickWaitHandlers,
+): () => void {
+  const view = target.ownerDocument.defaultView;
+  if (view == null) {
+    // A document with no window gets no click: the wait runs out at once.
+    let isEnded = false;
+    queueMicrotask(() => {
+      if (!isEnded) {
+        onNoClick();
+      }
+    });
+    return () => {
+      isEnded = true;
+    };
+  }
+  let isDone = false;
+  let report: number | null = null;
+  let timer: number | null = null;
+  let stopListening: (() => void) | null = null;
+  const stop = () => {
+    isDone = true;
+    stopListening?.();
+    stopListening = null;
+    if (timer != null) {
+      view.clearTimeout(timer);
+      timer = null;
+    }
+  };
+  stopListening = subscribeInput(view, 'click', event => {
+    if (
+      isDone ||
+      !event.isTrusted ||
+      !target.contains(event.target as Node | null)
+    ) {
+      return;
+    }
+    stop();
+    // After every handler has run: was it cancelled?
+    report = view.setTimeout(() => {
+      report = null;
+      onClicked(event.defaultPrevented);
+    }, 0);
+  });
+  timer = view.setTimeout(() => {
+    if (isDone) {
+      return;
+    }
+    stop();
+    onNoClick();
+  }, BROWSER_CLICK_WAIT_MS);
+  return () => {
+    stop();
+    if (report != null) {
+      view.clearTimeout(report);
+      report = null;
+    }
+  };
+}
+
+/**
+ * Click `element` (its own `click()`, so its activation behavior and every
+ * handler run as for any click) and report whether a handler cancelled it.
+ * The event is read from a capture listener that exists only for the call.
+ */
+export function clickAndReport(element: HTMLElement): boolean {
+  const view = element.ownerDocument.defaultView;
+  let clicked: Event | null = null;
+  const grab = (event: Event) => {
+    if (clicked == null && event.target === element) {
+      clicked = event;
+    }
+  };
+  view?.addEventListener('click', grab, true);
+  try {
+    element.click();
+  } finally {
+    view?.removeEventListener('click', grab, true);
+  }
+  return (clicked as Event | null)?.defaultPrevented === true;
+}
+
+/**
+ * Clicks `element` for a lift the control decided itself, and reports
+ * whether a handler cancelled the click. The shared click guard swallows the
+ * browser's own click for the same lift, if it comes later, so the lift
+ * activates once.
+ */
+export function clickForLift(element: HTMLElement): boolean {
+  armClickGuard(element.ownerDocument);
+  return withoutClickGuard(() => clickAndReport(element));
+}

package/src/utils/clickGuard.ts

@@ -26,6 +26,11 @@
 // `touchend`, aimed at whatever is under the finger by then. They go with
 // the click, the next `pointerdown` or the window, as the guard does.
 //
+// The menu press model's arm at a finger's release also cancels that touch's
+// `touchend`, so the browser creates no click and no compatibility mouse
+// events. A busy main thread can otherwise hold that click past the window,
+// when a drill-in has put another row under the finger.
+//
 // Some clicks always pass:
 // - a click with `detail` 0: a keyboard's, a screen reader's, or one that the
 //   page dispatches;
@@ -56,6 +61,13 @@ export interface ClickGuardOptions {
    * @default false
    */
   readonly takesLateMouse?: boolean;
+  /**
+   * The menu press model's arm at a finger's release: the guard also cancels
+   * that touch's `touchend`, so the browser creates no click for it. A
+   * cancelled `touchend` disarms the guard.
+   * @default false
+   */
+  readonly cancelsTouchEnd?: boolean;
 }
 
 interface Guard {
@@ -89,7 +101,11 @@ function listenForClicks(view: Window): () => void {
 /** Swallow the browser's next click on `doc` (see the file header). */
 export function armClickGuard(
   doc: Document,
-  {staysInstalled = false, takesLateMouse = false}: ClickGuardOptions = {},
+  {
+    staysInstalled = false,
+    takesLateMouse = false,
+    cancelsTouchEnd = false,
+  }: ClickGuardOptions = {},
 ): void {
   const view = doc.defaultView;
   if (view == null) {
@@ -116,6 +132,26 @@ export function armClickGuard(
       );
     }
   }
+  if (cancelsTouchEnd) {
+    // A touch sends its pointerup before its touchend, so the next touchend is
+    // that touch's own. The next pointerdown disarms the guard first.
+    const stopTouchEnd = subscribeInput(
+      view,
+      'touchend',
+      event => {
+        stopTouchEnd();
+        // A touchend that the browser took for a scroll is not cancelable.
+        // The guard stays armed for a click that may follow it.
+        if (event.cancelable) {
+          event.preventDefault();
+          // No click follows a cancelled touchend.
+          disarmClickGuard(doc);
+        }
+      },
+      {cancels: true},
+    );
+    guard.unsubscribers.push(stopTouchEnd);
+  }
   guard.timer = setTimeout(() => disarmClickGuard(doc), CLICK_GUARD_WINDOW_MS);
 }
 

package/dist/internal/tokenizer-presentation.d.ts

@@ -1,21 +0,0 @@
-/**
- * @file tokenizer-presentation.ts
- * @input Tokenizer's sheet-capable signature
- * @output `@astryxdesign/core/internal/tokenizer-presentation`: the Tokenizer
- *   with its `presentation` options reachable, for Astryx's own packages
- * @position An internal entry reserved for Astryx's own packages:
- *   undocumented, outside the public API and its compatibility promise
- *   (spec:AST-017 FR21), versioned in lockstep with Core, and allowed only in
- *   Core and Lab by the `@astryx/no-core-internal-import` lint rule
- *   (architecture:react-component-runtime INV13). The sheet presentation is
- *   implemented but not yet exposed: the public `TokenizerProps` offers no
- *   `experimental.presentation` while its user experience is being finished
- *   (`component:Tokenizer` DEC-3, implementation gap), and every public field
- *   renders the popover presentation. Named re-exports only.
- *
- * SYNC: When modified, update tokenizer-presentation.test.ts and
- * scripts/sync-exports.js.
- */
-export { TokenizerWithPresentation } from '../Tokenizer/Tokenizer.js';
-export type { TokenizerPresentationOptions, TokenizerWithPresentationProps, } from '../Tokenizer/Tokenizer.js';
-//# sourceMappingURL=tokenizer-presentation.d.ts.map

package/dist/internal/tokenizer-presentation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tokenizer-presentation.d.ts","sourceRoot":"","sources":["../../src/internal/tokenizer-presentation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAC,yBAAyB,EAAC,MAAM,wBAAwB,CAAC;AACjE,YAAY,EACV,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC"}

package/dist/internal/tokenizer-presentation.js

@@ -1,21 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file tokenizer-presentation.ts
- * @input Tokenizer's sheet-capable signature
- * @output `@astryxdesign/core/internal/tokenizer-presentation`: the Tokenizer
- *   with its `presentation` options reachable, for Astryx's own packages
- * @position An internal entry reserved for Astryx's own packages:
- *   undocumented, outside the public API and its compatibility promise
- *   (spec:AST-017 FR21), versioned in lockstep with Core, and allowed only in
- *   Core and Lab by the `@astryx/no-core-internal-import` lint rule
- *   (architecture:react-component-runtime INV13). The sheet presentation is
- *   implemented but not yet exposed: the public `TokenizerProps` offers no
- *   `experimental.presentation` while its user experience is being finished
- *   (`component:Tokenizer` DEC-3, implementation gap), and every public field
- *   renders the popover presentation. Named re-exports only.
- *
- * SYNC: When modified, update tokenizer-presentation.test.ts and
- * scripts/sync-exports.js.
- */
-export { TokenizerWithPresentation } from "../Tokenizer/Tokenizer.js";

package/src/internal/tokenizer-presentation.ts

@@ -1,25 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file tokenizer-presentation.ts
- * @input Tokenizer's sheet-capable signature
- * @output `@astryxdesign/core/internal/tokenizer-presentation`: the Tokenizer
- *   with its `presentation` options reachable, for Astryx's own packages
- * @position An internal entry reserved for Astryx's own packages:
- *   undocumented, outside the public API and its compatibility promise
- *   (spec:AST-017 FR21), versioned in lockstep with Core, and allowed only in
- *   Core and Lab by the `@astryx/no-core-internal-import` lint rule
- *   (architecture:react-component-runtime INV13). The sheet presentation is
- *   implemented but not yet exposed: the public `TokenizerProps` offers no
- *   `experimental.presentation` while its user experience is being finished
- *   (`component:Tokenizer` DEC-3, implementation gap), and every public field
- *   renders the popover presentation. Named re-exports only.
- *
- * SYNC: When modified, update tokenizer-presentation.test.ts and
- * scripts/sync-exports.js.
- */
-export {TokenizerWithPresentation} from '../Tokenizer/Tokenizer';
-export type {
-  TokenizerPresentationOptions,
-  TokenizerWithPresentationProps,
-} from '../Tokenizer/Tokenizer';