@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/dragPropagationLock.ts

@@ -0,0 +1,57 @@
+// REQ-GESTURE-024 / REQ-API-041 (R15 D1) — the nested-drag PROPAGATION LOCK, Motion's global
+// drag lock, PER AXIS (the pin's `motion-dom set-active.ts` at the §B pin): each axis holds
+// one non-propagating session at a time — `setDragLock('x'|'y')` takes that axis's flag;
+// `setDragLock(true)` (a both-axes drag) needs BOTH flags free and takes both, so an
+// orthogonal nested pair (outer y, inner x) runs TOGETHER while a second session on a held
+// axis is blocked. `dragPropagation={true}` skips the lock FOR ITSELF (never acquires, never
+// blocked — the propagation element's own start ignores the lock, per VEDC's onStart). The
+// lock is app-global (the pin's module-global analog, review 97bf73b720a8); the factory
+// exists so tests never share state; `reset` is the documented TEST seam for mount-level
+// suites sharing the process-wide lock (production never calls it).
+
+import type { DragAxis } from '@unrulysystems/native-motion-core'
+
+export interface DragPropagationLock {
+  // Take the lock for `owner` on ALL of `axes` ATOMICALLY (the pin's setDragLock semantics):
+  // returns false — holding NOTHING — when another owner already holds any needed axis.
+  acquire(owner: object, axes: readonly DragAxis[]): boolean
+  // Release every axis `owner` holds (its own sessions only — a release by a non-owner is a
+  // no-op, never a stolen lock).
+  release(owner: object): void
+  isHeld(axis: DragAxis): boolean
+  // TEST SEAM: force-clear all holders. Mount-level test files share the app-global singleton
+  // and a prior test's unfinished session would otherwise leak the lock into the next test.
+  reset(): void
+}
+
+export function createDragPropagationLock(): DragPropagationLock {
+  const holders: { x: object | null; y: object | null } = { x: null, y: null }
+  return {
+    acquire(owner, axes) {
+      for (const axis of axes) {
+        const holder = holders[axis]
+        if (holder !== null && holder !== owner) return false
+      }
+      for (const axis of axes) holders[axis] = owner
+      return true
+    },
+    release(owner) {
+      if (holders.x === owner) holders.x = null
+      if (holders.y === owner) holders.y = null
+    },
+    isHeld: (axis) => holders[axis] !== null,
+    reset() {
+      holders.x = null
+      holders.y = null
+    },
+  }
+}
+
+// The app-global default (the pin's module-global analog), used by every wiring that is not
+// given an explicit lock (unit tests inject their own via the factory above).
+export const sharedDragPropagationLock: DragPropagationLock = createDragPropagationLock()
+
+// TEST SEAM: clear the app-global lock between mount-level tests. Never called in production.
+export function resetSharedDragPropagationLock(): void {
+  sharedDragPropagationLock.reset()
+}