@symbiote-native/engine 1.3.0 → 1.4.0

package/build/events/names.d.ts

@@ -0,0 +1,24 @@
+export declare const BUBBLING_EVENTS: Readonly<Record<string, string>>;
+export declare const DIRECT_EVENTS: Readonly<Record<string, string>>;
+export declare const TOUCH_START = "topTouchStart";
+export declare const TOUCH_MOVE = "topTouchMove";
+export declare const TOUCH_END = "topTouchEnd";
+export declare const TOUCH_CANCEL = "topTouchCancel";
+export declare const PRESS = "press";
+export declare const RESPONDER_GRANT = "responderGrant";
+export declare const RESPONDER_REJECT = "responderReject";
+export declare const RESPONDER_START = "responderStart";
+export declare const RESPONDER_MOVE = "responderMove";
+export declare const RESPONDER_END = "responderEnd";
+export declare const RESPONDER_RELEASE = "responderRelease";
+export declare const RESPONDER_TERMINATE = "responderTerminate";
+export declare const RESPONDER_TERMINATION_REQUEST = "responderTerminationRequest";
+export declare const SHOULD_SET_NAMES: Readonly<Record<'start' | 'move', {
+    readonly capture: string;
+    readonly bubble: string;
+}>>;
+export declare const PRESS_IN = "pressIn";
+export declare const PRESS_OUT = "pressOut";
+export declare const LONG_PRESS = "longPress";
+export declare const DEFAULT_LONG_PRESS_MS = 500;
+export declare const LONG_PRESS_DEACTIVATION_DISTANCE = 10;

package/build/events/names.js

@@ -0,0 +1,80 @@
+// Raw Fabric event name -> listener name, and the synthesized names that have no raw event at all.
+// Kept apart from the handler so the file holding the strings is not the file read while debugging
+// a gesture
+// Bubbling events walk target -> root, direct ones fire on the target alone. `press` is synthesized
+// from a touch sequence and `layout` is direct, so neither is in these tables
+export const BUBBLING_EVENTS = {
+    topFocus: 'focus',
+    topBlur: 'blur',
+    topChange: 'change',
+    topEndEditing: 'endEditing',
+    topSubmitEditing: 'submitEditing',
+    topKeyPress: 'keyPress',
+};
+export const DIRECT_EVENTS = {
+    topLayout: 'layout',
+    topScroll: 'scroll',
+    topScrollBeginDrag: 'scrollBeginDrag',
+    topScrollEndDrag: 'scrollEndDrag',
+    topMomentumScrollBegin: 'momentumScrollBegin',
+    topMomentumScrollEnd: 'momentumScrollEnd',
+    topSelectionChange: 'selectionChange',
+    topContentSizeChange: 'contentSizeChange',
+    topLoadStart: 'loadStart',
+    topLoad: 'load',
+    topLoadEnd: 'loadEnd',
+    topError: 'error',
+    topProgress: 'progress',
+    topPartialLoad: 'partialLoad',
+    topRefresh: 'refresh',
+    topShow: 'show',
+    topRequestClose: 'requestClose',
+    topDismiss: 'dismiss',
+    topOrientationChange: 'orientationChange',
+    topTextLayout: 'textLayout',
+    topScrollToTop: 'scrollToTop',
+    // From RN's base ViewConfig, so any view may emit them. `accessibilityAction` fires on both
+    // platforms; the other three have no Android producer and are inert there
+    topAccessibilityAction: 'accessibilityAction',
+    topAccessibilityTap: 'accessibilityTap',
+    topMagicTap: 'magicTap',
+    topAccessibilityEscape: 'accessibilityEscape',
+};
+export const TOUCH_START = 'topTouchStart';
+export const TOUCH_MOVE = 'topTouchMove';
+export const TOUCH_END = 'topTouchEnd';
+export const TOUCH_CANCEL = 'topTouchCancel';
+export const PRESS = 'press';
+// The responder protocol (PanResponder / Touchable), post-`on` names: `onResponderMove` is
+// `responderMove` here. RN's negotiation and its two-phase walk live in `./responder`
+export const RESPONDER_GRANT = 'responderGrant';
+export const RESPONDER_REJECT = 'responderReject';
+export const RESPONDER_START = 'responderStart';
+export const RESPONDER_MOVE = 'responderMove';
+export const RESPONDER_END = 'responderEnd';
+export const RESPONDER_RELEASE = 'responderRelease';
+export const RESPONDER_TERMINATE = 'responderTerminate';
+export const RESPONDER_TERMINATION_REQUEST = 'responderTerminationRequest';
+// The should-set pair asked per phase, as one table т.к. the only thing separating a start
+// negotiation from a move one is which two names get asked
+export const SHOULD_SET_NAMES = {
+    start: {
+        capture: 'startShouldSetResponderCapture',
+        bubble: 'startShouldSetResponder',
+    },
+    move: {
+        capture: 'moveShouldSetResponderCapture',
+        bubble: 'moveShouldSetResponder',
+    },
+};
+// Synthesized alongside `press` so a Pressable can paint its pressed state. Both fire on the node
+// the touch STARTED on, `pressOut` on end and on cancel
+export const PRESS_IN = 'pressIn';
+export const PRESS_OUT = 'pressOut';
+// Synthesized from a sustained hold, so a bare Text or View gets `onLongPress` with no native
+// event behind it. A fired long press suppresses the tap on release
+export const LONG_PRESS = 'longPress';
+export const DEFAULT_LONG_PRESS_MS = 500;
+// How far the touch may drift before the pending long press is cancelled
+// (`Pressability.DEFAULT_LONG_PRESS_DEACTIVATION_DISTANCE`)
+export const LONG_PRESS_DEACTIVATION_DISTANCE = 10;

package/build/events/press.d.ts

@@ -0,0 +1,20 @@
+import { type ISymbioteNode } from '../node';
+export interface IPressGesture {
+    owner: ISymbioteNode;
+    longPressTimer: ReturnType<typeof setTimeout> | undefined;
+    longPressFired: boolean;
+    longPressStart: {
+        x: number;
+        y: number;
+    } | undefined;
+}
+export declare const activePresses: Set<IPressGesture>;
+export declare function clearLongPress(press: IPressGesture): void;
+export declare function takeAllPresses(): IPressGesture[];
+export declare function findActivePress(target: ISymbioteNode): IPressGesture | undefined;
+export declare function takeEndedPresses(nativeEvent: Record<string, unknown>): IPressGesture[];
+export declare function readTouchPoint(nativeEvent: Record<string, unknown>): {
+    x: number;
+    y: number;
+} | undefined;
+export declare function hasRemainingTouchWithin(owner: ISymbioteNode, nativeEvent: Record<string, unknown>): boolean;

package/build/events/press.js

@@ -0,0 +1,89 @@
+// The synthesized tap: Fabric has no `press` event, so one is built from a touch sequence. This
+// module owns the in-flight gestures and the long-press clock, nothing about delivery
+// A press is INDEPENDENT of the responder: `negotiateResponder` runs on the same touch frames and
+// neither consumes the other, т.к. a View can be a Pressable and a PanResponder target at once
+import { isRecord } from '../type-guards.js';
+import { isSymbioteNode } from '../node.js';
+import { endsWithin } from './delivery.js';
+// Each unrelated target owns an independent press, and further fingers under the same owner JOIN
+// it, so one target still sees exactly one `pressIn` / `press` / `pressOut` lifecycle
+export const activePresses = new Set();
+export function clearLongPress(press) {
+    if (press.longPressTimer !== undefined) {
+        clearTimeout(press.longPressTimer);
+        press.longPressTimer = undefined;
+    }
+}
+export function takeAllPresses() {
+    const presses = [...activePresses];
+    activePresses.clear();
+    for (const press of presses)
+        clearLongPress(press);
+    return presses;
+}
+export function findActivePress(target) {
+    for (const press of activePresses) {
+        if (endsWithin(target, press.owner))
+            return press;
+    }
+    return undefined;
+}
+// Every press whose last finger left in this frame, removed from the active set. An owner with a
+// finger still down keeps its press, which is what makes a multi-touch lift not a release
+export function takeEndedPresses(nativeEvent) {
+    const ended = [];
+    for (const press of activePresses) {
+        if (hasRemainingTouchWithin(press.owner, nativeEvent))
+            continue;
+        activePresses.delete(press);
+        clearLongPress(press);
+        ended.push(press);
+    }
+    return ended;
+}
+function pagePointOf(source) {
+    if (!source)
+        return undefined;
+    const { pageX, pageY } = source;
+    if (typeof pageX === 'number' && typeof pageY === 'number')
+        return { x: pageX, y: pageY };
+    return undefined;
+}
+// The changed finger's page coordinate, falling back to the active-touch list and then to
+// undefined, which callers read as "skip the coordinate-dependent logic" rather than guessing
+export function readTouchPoint(nativeEvent) {
+    const direct = pagePointOf(nativeEvent);
+    if (direct)
+        return direct;
+    // `changedTouches` identifies the finger for THIS frame, so it is read before the full
+    // active-touch list, whose first entry may belong to another simultaneously pressed target
+    for (const key of ['changedTouches', 'touches']) {
+        const touches = nativeEvent[key];
+        if (!Array.isArray(touches))
+            continue;
+        for (const touch of touches) {
+            if (!isRecord(touch))
+                continue;
+            const point = pagePointOf(touch);
+            if (point)
+                return point;
+        }
+    }
+    return undefined;
+}
+// Whether any touch still down started inside `owner`. RN's `noResponderTouches` walks
+// `nativeEvent.touches` the same way; a headless smoke fires an empty `{}`, so no remaining touch,
+// which preserves single-touch behavior
+export function hasRemainingTouchWithin(owner, nativeEvent) {
+    const touches = nativeEvent.touches;
+    if (!Array.isArray(touches))
+        return false;
+    for (const touch of touches) {
+        if (!isRecord(touch))
+            continue;
+        const target = touch.target;
+        if (isSymbioteNode(target) && endsWithin(target, owner))
+            return true;
+    }
+    return false;
+}

package/build/events/responder.d.ts

@@ -0,0 +1,6 @@
+import { type ISymbioteNode } from '../node';
+export declare function heldResponder(): ISymbioteNode | undefined;
+export declare function clearResponder(): void;
+/** Release the responder to native, on a final touch end or a terminate. */
+export declare function releaseResponderToNative(node: ISymbioteNode): void;
+export declare function negotiateResponder(target: ISymbioteNode, phase: 'start' | 'move', nativeEvent: Record<string, unknown>): void;

package/build/events/responder.js

@@ -0,0 +1,124 @@
+// The responder protocol: who owns the in-flight gesture, and the negotiation that moves it.
+// Split from `./index` so the touch handler reads as four phases rather than as the negotiation
+// `currentResponder` is module state reached from outside through `heldResponder` and
+// `clearResponder`, т.к. the touch handler must read it between its own phases
+import { dlog, isDebug } from '../debug.js';
+import { setIsJSResponder } from '../imperative.js';
+import { hasListenerFor } from '../node.js';
+import { callOwnListener, lowestCommonAncestor, pathToRoot } from './delivery.js';
+import { RESPONDER_GRANT, RESPONDER_REJECT, RESPONDER_TERMINATE, RESPONDER_TERMINATION_REQUEST, SHOULD_SET_NAMES, } from './names.js';
+// The node that claimed the responder for the in-flight touch, or undefined when nobody did.
+// Receives move and release/terminate
+let currentResponder;
+export function heldResponder() {
+    return currentResponder;
+}
+export function clearResponder() {
+    currentResponder = undefined;
+}
+// RN's two-phase should-set walk: CAPTURE root to deepest, then BUBBLE deepest to root, first true
+// wins. `skip` drops the deepest node when it IS the current responder, т.к. asking the holder to
+// re-claim would let its should-set consume the frame from under its own `onResponderMove`
+function findWantsResponder(path, phase, nativeEvent, skip) {
+    const names = SHOULD_SET_NAMES[phase];
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (path[i] !== skip &&
+            callOwnListener(path[i], names.capture, nativeEvent) === true) {
+            return path[i];
+        }
+    }
+    for (const node of path) {
+        if (node !== skip &&
+            callOwnListener(node, names.bubble, nativeEvent) === true)
+            return node;
+    }
+    return undefined;
+}
+// Tell native which node owns the gesture, RN's `injectGlobalResponderHandler`. The OLD owner
+// first, then the new one, both in one call so no site can do half of it
+// WITHOUT THIS A JS RESPONDER LOSES TO ANY SCROLL VIEW ABOVE IT, invisibly: the claim returns true,
+// the native UIScrollView never learns of it, and every later move arrives as `topScroll`
+function handOverNativeResponder(from, to, blockNativeResponder) {
+    if (isDebug()) {
+        dlog(`setIsJSResponder from=${from === undefined ? 'none' : 'yes'} ` +
+            `to=${to === undefined ? 'none' : 'yes'} block=${blockNativeResponder}`);
+    }
+    if (from !== undefined)
+        setIsJSResponder(from, false, blockNativeResponder);
+    if (to !== undefined)
+        setIsJSResponder(to, true, blockNativeResponder);
+}
+/** Release the responder to native, on a final touch end or a terminate. */
+export function releaseResponderToNative(node) {
+    handOverNativeResponder(node, undefined, false);
+}
+// The slice of the target's ancestry the negotiation may ask, plus the node it must not ask
+// ONE WALK, and the common case never needs a second: while a finger stays inside the view that
+// claimed it, the responder IS an ancestor of the target, so the scope RN computes as a lowest
+// common ancestor is already in the target's own path and an index lookup answers it
+function scopeFor(target) {
+    const targetPath = pathToRoot(target);
+    if (currentResponder === undefined)
+        return { path: targetPath, skip: undefined };
+    const heldAt = targetPath.indexOf(currentResponder);
+    if (heldAt >= 0)
+        return { path: targetPath.slice(heldAt), skip: currentResponder };
+    // The finger left the responder's subtree, a rare frame rather than every frame
+    const from = lowestCommonAncestor(currentResponder, target);
+    return { path: from === undefined ? [] : pathToRoot(from), skip: undefined };
+}
+function grantTo(wants, nativeEvent) {
+    currentResponder = wants;
+    if (isDebug())
+        dlog(`responder granted to ${wants.component}`);
+    const granted = callOwnListener(wants, RESPONDER_GRANT, nativeEvent);
+    handOverNativeResponder(undefined, wants, granted === true);
+}
+// RN's `setResponderAndExtractTransfer` order: grant the TAKER, then terminate the incumbent
+// RN also grants ahead of the termination request purely to read the block-native return. We have
+// no native surface to block, so on the REJECT path that grant is omitted as a visible no-op
+function transferTo(incumbent, wants, nativeEvent) {
+    // A missing termination-request listener means implicit consent (RN's default true), so only an
+    // explicit non-true answer keeps the incumbent
+    const guarded = hasListenerFor(incumbent, RESPONDER_TERMINATION_REQUEST);
+    const allowed = !guarded ||
+        callOwnListener(incumbent, RESPONDER_TERMINATION_REQUEST, nativeEvent) ===
+            true;
+    if (!allowed) {
+        if (isDebug())
+            dlog(`responder takeover of ${incumbent.component} rejected`);
+        callOwnListener(wants, RESPONDER_REJECT, nativeEvent);
+        return;
+    }
+    if (isDebug())
+        dlog(`responder transferred ${incumbent.component} -> ${wants.component}`);
+    const granted = callOwnListener(wants, RESPONDER_GRANT, nativeEvent);
+    callOwnListener(incumbent, RESPONDER_TERMINATE, nativeEvent);
+    currentResponder = wants;
+    handOverNativeResponder(incumbent, wants, granted === true);
+}
+// Negotiate (or re-negotiate) the responder for a touch start or move. With nobody holding it the
+// winner is granted; with an incumbent it is asked to relinquish first
+export function negotiateResponder(target, phase, nativeEvent) {
+    const { path, skip } = scopeFor(target);
+    if (path.length === 0)
+        return;
+    const wants = findWantsResponder(path, phase, nativeEvent, skip);
+    // Every exit is logged: a negotiation that declines is indistinguishable from one that never
+    // ran, and the two have opposite causes
+    if (!wants) {
+        if (isDebug()) {
+            dlog(`responder ${phase}: nobody wants it (path=${path.length}${skip === undefined ? '' : ', one skipped'})`);
+        }
+        return;
+    }
+    if (wants === currentResponder) {
+        if (isDebug())
+            dlog(`responder ${phase}: ${wants.component} already holds it`);
+        return;
+    }
+    if (currentResponder === undefined)
+        grantTo(wants, nativeEvent);
+    else
+        transferTo(currentResponder, wants, nativeEvent);
+}