@octane-xplat/motion 0.9.0 → 0.10.0

package/README.md

@@ -2,9 +2,28 @@
 
 Declarative numeric motion for Octane UI on web, iOS, and Android. Use
 `motion.View`, `motion.Row`, or `motion.Pressable` with `initial`, `animate`,
-and `transition`. Bound motion values update hosts without rendering each frame.
+and `transition`, or `drag` with numeric translation bounds. Bound motion values update hosts without rendering each frame.
 
-See the [motion guide](../../docs/animation-gestures.md) and maintained
+```tsx
+import { motion } from '@octane-xplat/motion'
+import { Text } from '@octane-xplat/ui'
+
+export function MovingCard() {
+	return (
+		<motion.View
+			initial={{ opacity: 0 }}
+			animate={{ opacity: 1 }}
+			transition={{ duration: 0.3 }}
+			drag="x"
+			dragConstraints={{ left: 0, right: 120 }}
+		>
+			<Text>Drag the packing card</Text>
+		</motion.View>
+	)
+}
+```
+
+See the [motion guide](../../docs/app/animation-gestures.md) and maintained
 [MotionDemo](examples/MotionDemo.tsrx). Use the [PresenceDemo](examples/PresenceDemo.tsrx) for retained exits.
 The [compatibility record](UPSTREAM.md)
 defines the supported subset and differences from `@octanejs/motion`.
@@ -13,3 +32,13 @@ Build with `pnpm --filter @octane-xplat/motion build`; run DOM/engine tests with
 `pnpm --filter @octane-xplat/motion test` and universal lifecycle tests with
 `pnpm --filter @octane-xplat/motion exec vitest run --config vitest.native.config.mts`.
 Native compilation and object-driver tests are not physical-device evidence.
+
+Native consumers must install `@nativescript-community/gesturehandler` and call
+its `install()` before creating the root. See [drag setup](../../docs/app/animation-gestures.md#drag-a-component). Web does not require this optional peer.
+
+```ts
+// bootstrap.mobile.ts — before Application.run or creating Page/Frame roots.
+import { install } from '@nativescript-community/gesturehandler'
+
+install()
+```

package/UPSTREAM.md

@@ -16,6 +16,11 @@ The adapter is original code; it does not copy upstream's DOM host factory.
 | Config and reduced motion                        | src/context.ts; tests/conformance/reducedMotionConfig.test.ts     | Context inheritance; spring transforms settle immediately on live preference changes while opacity can keep animating (`components.web.test.tsrx`, `engine.test.ts`) |
 | Exit lifecycle                                   | src/index.ts; tests/conformance/exit.test.ts                      | Deliberate live-subtree retention on both leaves; presence.web.test.tsrx and native presence test                                                                    |
 | Retained hosts on native                         | Not a DOM binding concern                                         | components.mobile.test.tsrx uses the universal object driver                                                                                                         |
+| Bounded drag                                     | src/index.ts pointer-drag binding; upstream/src/gestures/drag     | Numeric constraints, scalar elasticity, callbacks, JS velocity spring; drag.test.ts and web/native handler tests                                                     |
+| Interaction targets                              | whileTap/whileFocus gesture bindings                              | Host-level gesture seam (PointerEvents/touch/focus); snapshot + restore; components.web.test.tsrx, motion probe                                                      |
+| Variant labels and bounded orchestration         | src/context.ts; src/index.ts variant inheritance/stagger          | variants.test.ts, web/native compiled host tests; numeric resolution before Controller                                                                               |
+| Scoped imperative runs                           | useAnimate                                                        | Controller registry keyed on host nodes; `ref` accepts callback refs and `{current}` scopes                                                                          |
+| Custom host components                           | motion.create / motion.<tag>                                      | `motion.create(Component)` wraps shared-UI leaves; DOM tag proxy excluded                                                                                            |
 
 Source links: [Octane motion](https://github.com/octanejs/octane/tree/main/packages/motion),
 [upstream ledger](https://github.com/octanejs/octane/blob/main/packages/motion/UPSTREAM.md),
@@ -23,8 +28,11 @@ Source links: [Octane motion](https://github.com/octanejs/octane/tree/main/packa
 
 ## Deliberate boundaries
 
-- Numeric values only. No CSS strings, keyframe arrays, variants, layout,
-  gesture presets, declarative drag, or broad framework-neutral re-export.
+- Numeric values only. No CSS strings, keyframe arrays, layout/layoutId,
+  `whileHover`/`whileInView`, or broad framework-neutral re-export. Bounded drag,
+  variants, `whileTap`, `whileFocus`, lifecycle callbacks
+  (`onAnimationStart`/`onAnimationComplete`/`onUpdate`), `motion.create`, and
+  `useAnimate` match the upstream prop names.
 - Host APIs use shared UI names rather than DOM tags. Existing UI props remain
   available; motion owns transform channels and opacity. Put pre-existing CSS
   transforms on an outer container. Conflicting writers are errors.
@@ -33,14 +41,231 @@ Source links: [Octane motion](https://github.com/octanejs/octane/tree/main/packa
 - MotionConfig defaults to `reducedMotion="never"`, matching the reference;
   choose `user` for system preferences. Config does not cross separate roots and
   does not alter imperative value.animate calls: consult useReducedMotion there.
-- Timing uses a platform clock. NativeScript exposes frame scheduling through a
-  module; Motion's scheduler captures a global rAF and its values use browser
-  timing globals. The numeric adapter avoids changing application globals.
-- The same generator runs on web/native. WAAPI and native Animation acceleration
-  are deferred until interruption and transform composition preserve this contract.
-- Springs are physical (not duration/bounce based); duration belongs to tweens.
-  Default declarative transition is a 0.3-second easeInOut tween. Targets are
-  absolute; scale multiplies scaleX/scaleY. Opacity is clamped to 0–1 at the host. Reduced transforms have no delay.
+- Timing uses a monotonic platform clock (`System.nanoTime`/`CADisplayLink`-derived
+  on native, `performance.now` on web) with NativeScript's vsync scheduler.
+- The same generator runs on web/native. Declarative tweens delegate to the
+  platform animator (`UIViewPropertyAnimator` on iOS, `ViewPropertyAnimator`
+  on Android, WAAPI `element.animate` on web) with per-frame presentation
+  tracking so interruption hands off value and velocity to the JS engine;
+  springs, reduced-motion runs, and gesture-driven values always run on the
+  JS engine. The web driver animates a matched function-list transform
+  keyframe plus `opacity`; sampled matrices decompose back to channels with
+  rotate read modulo ±180° and scale signs folded per the matrix.
+- Springs accept both the physical spec (stiffness/damping/mass/velocity) and
+  upstream's duration/bounce spec. Transitions support `repeat`/`repeatType`
+  (`loop`/`reverse`/`mirror`)/`repeatDelay` and per-channel overrides in the
+  `{x: {…}, default: {…}}` form. Default declarative transition is a 0.3-second
+  easeInOut tween. Targets are absolute; scale multiplies scaleX/scaleY.
+  Opacity is clamped to 0–1 at the host. Reduced transforms have no delay.
+  Non-bezier eases, springs, repeats, and per-key transitions refuse platform
+  delegation and run on the JS engine on all targets.
+
+## Bounded declarative drag
+
+Decision #94 widens the exclusions recorded in #92. `drag={true}` moves both
+axes; `drag="x"`/`"y"` owns one axis. Numeric `dragConstraints` edges are
+absolute translation limits in CSS pixels/DIP; omitted edges are unbounded.
+Measured-ref constraints are rejected explicitly. `dragElastic` is a scalar
+0–1 (default 0.35; false = 0, true = 0.35), with linear resistance outside
+bounds. Per-edge elasticity objects are excluded.
+
+```tsx
+import { motion } from '@octane-xplat/motion'
+
+export function DraggableCard() {
+	return <motion.View drag="x" dragConstraints={{ left: 0, right: 120 }} dragElastic={0.2} />
+}
+```
+
+`onDragStart`, `onDrag`, and `onDragEnd` receive `(event, info)`, where info has
+`point`, `delta`, `offset`, `velocity` (units/second), and `cancelled`. Point is
+viewport/screen coordinates. Offset and delta describe pointer movement before
+constraints. Start fires on activation after an 8-unit threshold, rather than
+on pointer-down; unsuccessful pre-activation gestures emit no drag callbacks.
+Cancellation emits one end callback and suppresses momentum. Disposal removes
+input handlers and stops settlement without emitting an end callback.
+
+```tsx
+// motion is imported above; callbacks report gesture movement before constraints.
+export function DragEvents() {
+	return (
+		<motion.View
+			drag
+			onDragStart={(_event, info) => console.log(info.point)}
+			onDrag={(_event, info) => console.log(info.delta, info.offset)}
+			onDragEnd={(_event, info) => console.log(info.velocity, info.cancelled)}
+		/>
+	)
+}
+```
+
+Release projects `current + velocity * 0.2`, clamps the destination, and uses a
+JS spring (stiffness 200, damping 30). `dragMomentum={false}` keeps the current
+position if in bounds, or springs back from elastic overflow. This is a bounded
+spring settle, **not upstream's inertia/decay algorithm**. Hard constraints
+(`dragElastic={false}`) clamp every spring sample before host/value notification.
+Reduced motion snaps release settlement; pointer tracking remains live.
+
+```tsx
+export function BoundedCard() {
+	return (
+		<motion.View
+			drag="x"
+			dragConstraints={{ left: 0, right: 120 }}
+			dragElastic={false}
+			dragMomentum={false}
+		/>
+	)
+}
+```
+
+A plain or spring-backed `style.x`/`style.y` MotionValue can receive drag writes;
+live writes use `jump` so passive spring following cannot lag the pointer.
+Drag axes reject competing `animate`, `whileTap`, or `whileFocus` targets;
+`initial` seeds the position and `exit` can own it after interaction ends.
+No ref measurement, dragControls, dragListener, direction lock, propagation,
+snap-to-origin, dragTransition, onDragTransitionEnd, or layout projection is
+implemented. `drag` axis selection is not `dragDirectionLock`.
+
+```tsx
+import { motion, useMotionValue } from '@octane-xplat/motion'
+
+export function LivePosition() {
+	const x = useMotionValue(0)
+	return <motion.View drag="x" style={{ x }} initial={{ x: 0 }} exit={{ x: -100 }} />
+}
+```
+
+Web uses host PointerEvents/capture and `touch-action: pan-y` for horizontal
+drag, `pan-x` for vertical drag, or `none` for both. Native imports the optional
+peer `@nativescript-community/gesturehandler` (pinned to 2.0.45); native consumers
+must install it even when using only other motion APIs because the native
+entry imports its adapter. Web consumers do not need it. Apps call `install()`
+before creating their Page/Frame/root; **do not call `install(true)`**, which
+would replace existing NS gesture observers. There is no raw-pan fallback.
+Motion reserves handler tags from 700000000 upward within its single module
+instance. Native axis activation/failure uses 8 DIP; 2.0.45's Android config
+setters need explicit DIP→pixel conversion while payloads already return DIP.
+On Android single-axis handlers disable the default radial slop trigger so
+only the selected axis can activate. The plugin's Manager owns view-init/dispose attachment; motion removes its
+state/touch listeners and detaches on cleanup.
+
+```ts
+// Native bootstrap .mobile.ts, before creating Page/Frame/root hosts.
+import { install } from '@nativescript-community/gesturehandler'
+
+install() // Preserve existing NativeScript gesture observers.
+```
+
+NativeViewGestureHandler is not needed for the bounded surface: motion attaches
+PanGestureHandler directly to its host, with no simultaneous/waitFor graph.
+Nested native control ownership and complex competing drags are deferred.
+Threshold configuration is source/test evidence of arbitration policy; only
+real OS input inside a ScrollView can establish runtime arbitration.
+
+## Variants (decision #93)
+
+`variants` maps labels to numeric targets with an optional `transition`, or to
+`(custom) => target` resolvers. The host's `custom` is passed to its own resolver;
+current values and velocities are not resolver arguments. `initial`, `animate`,
+`exit`, `whileTap`, and `whileFocus` accept targets, labels, or label arrays.
+Arrays merge targets left to right; later channels win. Missing labels are
+ignored. The last defined variant transition replaces the host/config transition
+for that run; otherwise the normal default applies. Per-key transitions remain
+supported. Resolvers should be pure; they may be evaluated during validation.
+
+```tsx
+export function LabelledMotion() {
+	return (
+		<motion.View
+			custom={80}
+			initial="hidden"
+			animate={['shown', 'offset']}
+			variants={{
+				hidden: { opacity: 0 },
+				shown: { opacity: 1 },
+				offset: (custom: number) => ({ x: custom, transition: { duration: 0.2 } }),
+			}}
+		/>
+	)
+}
+```
+
+Initial labels (including `initial={false}`) inherit through a root-local
+context. Animate labels propagate to descendant motion hosts without their own
+`animate`; each host resolves its own map and `custom`. Ordinary UI wrappers do
+not break propagation. An explicit `animate` makes that host an independent
+animation subtree. Direct target objects are not inherited. Both shared motion
+hosts and `motion.create` provide the context.
+
+```tsx
+import { View } from '@octane-xplat/ui'
+import { motion } from '@octane-xplat/motion'
+
+const CustomMotionView = motion.create(View)
+export function InheritedMotion() {
+	return (
+		<CustomMotionView initial="hidden" animate="shown">
+			<motion.View variants={{ hidden: { opacity: 0 }, shown: { opacity: 1 } }} />
+		</CustomMotionView>
+	)
+}
+```
+
+On label-driven **animate** runs, the parent's resolved transition supports
+numeric non-negative `delayChildren` and `staggerChildren` in seconds, applied
+in child registration order and added to the child's own channel delays.
+`when: 'beforeChildren'` waits for successful parent completion;
+`'afterChildren'` waits for all inherited children; omitting `when` runs both
+concurrently. Nested runs wait for their own descendants. Replacement and
+unmount invalidate queued phases. A child mounted after a run starts joins
+once that run completes, with fresh child delay; it does not extend that run's
+completion barrier. Changing a retained child's resolved target/custom starts
+its own inherited run. Registration order does not track keyed visual reorders.
+
+```tsx
+export function StaggeredCards() {
+	return (
+		<motion.View
+			animate="shown"
+			variants={{
+				shown: {
+					opacity: 1,
+					transition: { delayChildren: 0.1, staggerChildren: 0.05, when: 'beforeChildren' },
+				},
+			}}
+		>
+			<motion.View variants={{ shown: { x: 40 } }} />
+			<motion.View variants={{ shown: { x: 80 } }} />
+		</motion.View>
+	)
+}
+```
+
+Exit and interaction labels resolve locally: they do not propagate activation
+or child timing. Presence continues waiting for each registered host's explicit
+exit; specify `exit` on children that need one. Callback completion remains
+per-host playback, rather than a tree completion event. Unsupported upstream
+semantics include `inherit={false}`, dynamic delay functions, `staggerDirection`,
+`stagger()` helpers, gesture priority blending, `transitionEnd`, resolver chains,
+and inheritance across separate renderer roots. Resolved targets and ordinary
+transitions enter Controller unchanged, retaining existing delegation gates.
+
+```tsx
+import { Presence, motion } from '@octane-xplat/motion'
+
+export function ExitingCards({ present }: { present: boolean }) {
+	return (
+		<Presence present={present}>
+			<motion.View
+				exit="hidden"
+				variants={{ hidden: { opacity: 0 } }}
+				onAnimationComplete={() => console.log('This host completed')}
+			/>
+		</Presence>
+	)
+}
+```
 
 ## Presence divergence
 
@@ -51,12 +276,52 @@ reuse that path or claim its cleanup timing. Presence renders an explicit View
 wrapper, blocks interaction during exit, and restores interaction on reversal.
 An ancestor unmount always disposes immediately. Nested boundaries are independent.
 
+```tsx
+import { useState } from 'octane'
+import { Presence, motion } from '@octane-xplat/motion'
+import { Button, Text } from '@octane-xplat/ui'
+
+export function RetainedCard() {
+	const [present, setPresent] = useState(true)
+	return (
+		<>
+			<Button onPress={() => setPresent(!present)}>Toggle card</Button>
+			<Presence present={present}>
+				<motion.View exit={{ opacity: 0 }}>
+					<Text>Trip card</Text>
+				</motion.View>
+			</Presence>
+		</>
+	)
+}
+```
+
 ## Verification limits
 
+Web WAAPI delegation (2026-10-02): unit tests drive a fake `Animation` through
+the real web adapter for keyframe shape, matrix/matrix3d decomposition with
+transform-origin correction, cancel-before-sample ordering, mid-flight
+value/velocity handoff, and bezier-only gating; the retained probe passes on
+headless Chromium with delegation counters engaged (14 starts, 10 finishes, 4
+cancellations, 0 fallbacks). DOM dispatch evidence only — compositor pacing is
+not asserted.
+
+Bounded drag (2026-10-02): the maintained probe passes 14 assertions on web
+Chromium and 14 on the requested iOS simulator, including live writes, bounded
+momentum, callbacks, and cancellation. Native input is plugin handler dispatch;
+it does not prove OS hit-testing or drag-versus-scroll arbitration. Android drag
+runtime remains unverified. Package unit/build/packed-consumer checks cover the
+public types and shared numeric behavior.
+The variants expansion passes 60 standard tests and 5 native object-driver
+tests. The maintained probe passes 11 assertions on web Chromium and the iOS
+simulator (2026-10-02), including inherited custom destinations and
+parent-before-children stagger completion order; iOS platform delegation engages.
+No Android runtime was available for this expansion.
+
 Unit and DOM tests establish bounded behavior, not full Framer Motion parity.
 Universal object-driver tests establish retention and lifecycle without an OS.
 Partial device observations are recorded in the
-[motion v1 validation matrix](../../docs/animation-notes.md). An isolated iOS
+[motion v1 validation matrix](../../docs/notes/animation-notes.md). An isolated iOS
 26.5 MotionProbe run verified pan completion/cancellation, Presence
 focus/reversal/removal, and live Reduce Motion, including immediate transform
 settlement. The API 35 Android emulator verified tween/spring completion,
@@ -86,9 +351,12 @@ Physical Android CPH2551 evidence covers app launch and target retarget only;
 ADB sees the handset, but its keyguard is currently locked. The regular mobile app now builds and
 mounts on the iOS 26.5 simulator using NativeScript's `NSObject.extend()` API
 for the auth-session presentation delegate. The Android build also passes with
-the iOS delegate behind the `NSObject` runtime guard. Motion-specific simulator,
-emulator, and iPhone checks still use a temporary direct MotionProbe entry to
-isolate the driver. Physical input suppression during exit, Android gesture
+the iOS delegate behind the `NSObject` runtime guard. The maintained
+`examples/probes/motion.tsrx` case replaces the earlier temporary direct
+MotionProbe entry (web Chromium and iOS simulator passes, 2026-10-02).
+Physical input suppression during exit, Android gesture
 cancellation/natural velocity, background/resume, and frame pacing remain
-uncharacterized. Native preference observation polls at 500 ms while subscribed
-and refreshes on resume; Android reads `animator_duration_scale`.
+uncharacterized. On iOS the preference is observed through
+`UIAccessibilityReduceMotionStatusDidChangeNotification`; Android still polls
+`animator_duration_scale` at 500 ms while subscribed (plus
+`ValueAnimator.areAnimatorsEnabled()` on API 26+) and refreshes on resume.