@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/dragAncestorPanContext.ts

@@ -0,0 +1,28 @@
+// REQ-GESTURE-024 / REQ-API-041 (R15 D1, reviews 4af62c2d1b77 + round-9 + round-10) — the
+// drag-ancestor pan channel. Each drag-carrying MotionView provides its Pan recognizer, its
+// own dragPropagation flag, and its drag axes to descendants; the nearest child composes
+// `simultaneousWithExternalGesture` against the ancestor's pan whenever both recognizers must
+// be able to activate on one stream: either side propagates (the carrier skips the lock for
+// itself — parent or child), OR the nested pair's axis sets are DISJOINT (the pin's per-axis
+// lock permits an orthogonal pair concurrently, and RNGH's competing-arbitration must not
+// cancel one side before the JS lock policy runs — review round-10 major). A same-axis
+// default pair stays competing: the per-axis lock arbitrates it. Non-drag hosts pass the
+// inherited value through unchanged.
+
+import { createContext, useContext } from 'react'
+import type { PanGesture } from 'react-native-gesture-handler'
+import type { DragAxis } from '@unrulysystems/native-motion-core'
+
+export interface DragAncestorPanEntry {
+  readonly pan: PanGesture
+  readonly propagation: boolean
+  readonly axes: readonly DragAxis[]
+}
+
+const DragAncestorPanContext = createContext<DragAncestorPanEntry | null>(null)
+
+export function useDragAncestorPan(): DragAncestorPanEntry | null {
+  return useContext(DragAncestorPanContext)
+}
+
+export const DragAncestorPanProvider = DragAncestorPanContext.Provider

package/src/native/motion/dragControls.ts

@@ -0,0 +1,152 @@
+// REQ-GESTURE-026 / REQ-API-043 (R15 D3) — the imperative DragControls hub.
+// Pin: motion/packages/framer-motion/src/gestures/drag/use-drag-controls.ts
+//
+// A hub fans out start/cancel/stop to every subscribed draggable (the pin's Set broadcast).
+// Each subscriber is the element-local session controller; the hub never owns motion values.
+// Native Finding 8 maps the pin's per-element window PanSession to ONE MotionRoot stream:
+// concurrent multi-subscriber hub start is last-writer-wins on that stream (documented;
+// product rows use one draggable per hub). Cancel/stop still fan out to every subscriber.
+// `useDragControls` returns a lifetime-constant hub instance (pin useConstant).
+//
+// start(event, options) semantics (pin VisualElementDragControls.start):
+//   - snapToCursor (default false): re-seat each axis so the grab point is the element center
+//     (sanctioned G-INV-2 jump at start-invocation only)
+//   - distanceThreshold (default 3): movement gate before the session activates (PanSession)
+//
+// cancel() maps to REQ-GESTURE-018 (pre-grab return). The pin's bare cancel leaves the value
+// unsettled — native-motion applies settle-totality (G-INV-7) via the handoff cancel path; a
+// settle-totality divergence is recorded if product walks ever require pin-identical bare cancel.
+// stop() = cancel + release animation from the latest event/info when args are omitted.
+
+import {
+  validateDragControlOptions,
+  type DragControlOptions as CoreDragControlOptions,
+} from '@unrulysystems/native-motion-core'
+import { useRef } from 'react'
+
+/** Options accepted by `DragControls.start` (pin DragControlOptions). */
+export type DragControlOptions = CoreDragControlOptions
+
+/** Re-export shared start-options validator (G-INV-8; seal review r6/r7; core single-source). */
+export { validateDragControlOptions }
+
+/**
+ * The element-local session controller a View registers with a hub.
+ * Implemented by the drag wiring / MotionView subscription — never by product code.
+ * @internal
+ */
+export interface DragControlsSubscriber {
+  start(event: unknown, options?: DragControlOptions): void
+  cancel(): void
+  stop(): void
+}
+
+/**
+ * Imperative drag hub — start/cancel/stop every subscribed drag-enabled View.
+ *
+ * ```tsx
+ * const dragControls = useDragControls()
+ * function startDrag(event: unknown) {
+ *   dragControls.start(event, { snapToCursor: true })
+ * }
+ * return (
+ *   <>
+ *     <Pressable onPressIn={startDrag} />
+ *     <View drag="x" dragControls={dragControls} dragListener={false} />
+ *   </>
+ * )
+ * ```
+ *
+ * @public
+ */
+export class DragControls {
+  private readonly subscribers = new Set<DragControlsSubscriber>()
+
+  /**
+   * Subscribe a component's internal session controller. Returns the unsubscribe.
+   * @internal
+   */
+  subscribe(controls: DragControlsSubscriber): () => void {
+    this.subscribers.add(controls)
+    return () => {
+      this.subscribers.delete(controls)
+    }
+  }
+
+  /**
+   * Start a drag on every subscribed View using the originating event's pointer position.
+   * Fail-loud when no View is subscribed — a silent no-op would drop a product start
+   * (REQ-GESTURE-026; G-INV-8). Development throws; production reports via console.
+   * @public
+   */
+  start(event: unknown, options?: DragControlOptions): void {
+    // Validate before fan-out so a malformed option never silently changes threshold/snap
+    // behavior at the stream (seal review r6 minor; G-INV-8).
+    let validated: DragControlOptions | undefined
+    try {
+      validated = validateDragControlOptions(options)
+    } catch (error) {
+      // Mirror the component boundary: development throws, production reports.
+      // eslint-disable-next-line no-undef -- RN/metro __DEV__ global
+      if (typeof __DEV__ !== 'undefined' ? __DEV__ : process.env.NODE_ENV !== 'production') {
+        throw error
+      }
+      console.error(error)
+      return
+    }
+    if (this.subscribers.size === 0) {
+      const error = new Error(
+        'DragControls.start: no subscribed drag View — attach dragControls={hub} on a ' +
+          'drag-enabled View before start (REQ-GESTURE-026; G-INV-8).',
+      )
+      // Mirror the component boundary: development throws, production reports.
+      // eslint-disable-next-line no-undef -- RN/metro __DEV__ global
+      if (typeof __DEV__ !== 'undefined' ? __DEV__ : process.env.NODE_ENV !== 'production') {
+        throw error
+      }
+      // Production: report once; never silent.
+      console.error(error)
+      return
+    }
+    for (const controls of this.subscribers) {
+      controls.start(event, validated)
+    }
+  }
+
+  /**
+   * Cancel active sessions on every subscriber (REQ-GESTURE-018 pre-grab return).
+   * @public
+   */
+  cancel(): void {
+    for (const controls of this.subscribers) {
+      controls.cancel()
+    }
+  }
+
+  /**
+   * Stop active sessions and run the release animation (pin-shaped zero-arg public API).
+   * @public
+   */
+  stop(): void {
+    for (const controls of this.subscribers) {
+      controls.stop()
+    }
+  }
+
+  /** @internal test/debug surface */
+  get subscriberCount(): number {
+    return this.subscribers.size
+  }
+}
+
+/**
+ * Lifetime-constant DragControls hub (pin useConstant).
+ * @public
+ */
+export function useDragControls(): DragControls {
+  const ref = useRef<DragControls | null>(null)
+  if (ref.current === null) {
+    ref.current = new DragControls()
+  }
+  return ref.current
+}