@octane-xplat/motion 0.0.0 → 0.7.0

package/dist/web/octane-client-build.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "buildId": "3031c781-97bb-4558-8503-b4cf213f420e",
+  "mode": "production",
+  "capabilities": {
+    "independentHydration": false
+  }
+}

package/package.json

@@ -1,6 +1,60 @@
 {
-	"name": "@octane-xplat/motion",
-	"version": "0.0.0",
-	"description": "Stub reserving the name; real releases publish from CI via trusted publishing.",
-	"publishConfig": {"access": "public"}
-}
+  "name": "@octane-xplat/motion",
+  "version": "0.7.0",
+  "description": "Declarative motion and retained presence for Octane on web, iOS and Android",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octane-xplat/octane-xplat.git",
+    "directory": "packages/motion"
+  },
+  "files": [
+    "dist",
+    "types",
+    "src",
+    "LICENSE.motion",
+    "UPSTREAM.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "web": "./dist/web/index.js",
+      "native": "./dist/native/index.js",
+      "default": "./dist/native/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@octane-xplat/ui": "0.7.0",
+    "motion-dom": "12.42.2"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.1",
+    "@nativescript/core": "9.1.2",
+    "@octanejs/vite-plugin": "0.1.61",
+    "jsdom": "30.1.1",
+    "octane": "0.6.3",
+    "typescript": "5.9.3",
+    "vite": "8.3.0",
+    "vitest": "5.0.1"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "octane": ">=0.1.51 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vite build && vite build --mode native && tsc -p tsconfig.types.json",
+    "test": "vitest run"
+  }
+}

package/src/clock-types.ts

@@ -0,0 +1,6 @@
+/** Frame scheduler; timestamps and elapsed time are milliseconds. */
+export interface Clock {
+	now(): number
+	request(callback: () => void): number
+	cancel(id: number): void
+}

package/src/clock.ts

@@ -0,0 +1,7 @@
+import { requestAnimationFrame, cancelAnimationFrame } from '@nativescript/core/animation-frame'
+import type { Clock } from './clock-types'
+export const clock: Clock = {
+	now: () => Date.now(),
+	request: requestAnimationFrame,
+	cancel: cancelAnimationFrame,
+}

package/src/clock.web.ts

@@ -0,0 +1,6 @@
+import type { Clock } from './clock-types'
+export const clock: Clock = {
+	now: () => performance.now(),
+	request: (callback) => requestAnimationFrame(callback),
+	cancel: (id) => cancelAnimationFrame(id),
+}

package/src/components.mobile.test.tsrx

@@ -0,0 +1,84 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { describe, expect, it } from 'vitest'
+import { createObjectContainer, createObjectDriver, createUniversalRoot, flushUniversalSync } from 'octane/universal/native'
+import { motion, MotionConfig } from './index'
+
+function NativeBox(props: any) @{
+	<MotionConfig reducedMotion="always">
+		<motion.View id="native" initial={{ x: 10 }} animate={{ x: props.x }} transition={{ duration: 20 }} />
+	</MotionConfig>
+}
+
+describe('native compiled hosts', () => {
+	it('updates retained hosts through universal context and props', () => {
+		const container = createObjectContainer('nativescript')
+		const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+		root.render(NativeBox, { x: 50 })
+		const node: any = container.children[0]
+		expect(node.translateX).toBe(50)
+		flushUniversalSync(() => root.render(NativeBox, { x: 80 }))
+		expect(container.children[0]).toBe(node)
+		expect(node.translateX).toBe(80)
+		root.unmount()
+		expect(container.children.length).toBe(0)
+	})
+})
+
+import { vi } from 'vitest'
+import { useEffect } from 'octane'
+import { Presence } from './index'
+let nativeCleanups = 0
+function NativeChild() @{
+	useEffect(() => () => { nativeCleanups++ }, [])
+
+	<motion.View id="child" animate={{ x: 0 }} exit={{ x: 100 }} transition={{ duration: 0.1 }} />
+}
+
+function NativePresence(props: any) @{
+	<Presence present={props.present} onExitComplete={props.done}><NativeChild /></Presence>
+}
+
+describe('native presence lifecycle', () => {
+	it('retains and reverses a live subtree, then removes exactly once', async () => {
+		vi.useFakeTimers(); nativeCleanups = 0
+		const container = createObjectContainer('nativescript')
+		const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+		const done = vi.fn()
+		root.render(NativePresence, { present: true, done })
+		const boundary: any = container.children[0]
+		const child = boundary.children[0]
+		root.render(NativePresence, { present: false, done })
+		expect(boundary.isUserInteractionEnabled).toBe(false)
+		expect(nativeCleanups).toBe(0)
+		await vi.advanceTimersByTimeAsync(32)
+		root.render(NativePresence, { present: true, done })
+		await vi.advanceTimersByTimeAsync(200)
+		flushUniversalSync(() => {})
+		expect(container.children[0]).toBe(boundary)
+		expect(boundary.children[0]).toBe(child)
+		expect(nativeCleanups).toBe(0); expect(done).not.toHaveBeenCalled()
+		root.render(NativePresence, { present: false, done })
+		await vi.advanceTimersByTimeAsync(200)
+		flushUniversalSync(() => {})
+		expect(container.children.length).toBe(0)
+		expect(nativeCleanups).toBe(1); expect(done).toHaveBeenCalledTimes(1)
+		root.unmount(); vi.useRealTimers()
+	})
+})
+
+import { signal$ } from 'octane/signals'
+const destination$ = signal$(0)
+function NativeSignal() @{
+	<motion.Pressable onPress={() => destination$.set(75)} animate={{ x: destination$.get() }} transition={{ duration: 0 }} />
+}
+
+it('retargets a retained native host on a signal write', () => {
+	const container = createObjectContainer('nativescript')
+	const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+	root.render(NativeSignal, {})
+	const node: any = container.children[0]
+	flushUniversalSync(() => container.dispatchEvent(node, 'tap', {}))
+	expect(container.children[0]).toBe(node)
+	expect(node.translateX).toBe(75)
+	root.unmount()
+})

package/src/components.tsrx

@@ -0,0 +1,142 @@
+import { useRef, useLayoutEffect, useContext } from 'octane'
+import { View, Row, Pressable } from '@octane-xplat/ui'
+import { ConfigContext, useReducedMotion } from './config.tsrx'
+import { PresenceContext } from './presence.tsrx'
+import type { PresenceMember } from './presence-state'
+import { clock } from './clock'
+import { attachHost } from './host'
+import type { HostAdapter } from './host-types'
+import { Controller, keys, defaults, validateTarget } from './controller'
+import { validateTransition } from './engine'
+import { MotionValue } from './value'
+import type { MotionKey, MotionProps, MotionViewProps, MotionRowProps, MotionPressableProps, Target } from './types'
+
+function useMotion(props: MotionProps & { bind?: (host: any) => void }) {
+	for (const name of ['drag', 'layout', 'layoutId', 'variants', 'whileTap', 'whileHover', 'whileFocus', 'whileInView']) {
+		if (name in props) throw new Error(`motion: ${name} is outside the supported subset`)
+	}
+
+	const presence = useContext(PresenceContext)
+	if (props.exit && !presence) throw new Error('motion: exit requires a mounted Presence boundary')
+	const config = useContext(ConfigContext)
+	const systemReduced = useReducedMotion()
+	const reduced = config.reducedMotion === 'always' || (config.reducedMotion === 'user' && systemReduced)
+	const transition = props.transition ?? config.transition ?? {}
+	validateTransition(transition)
+	validateTarget(props.animate)
+	validateTarget(props.exit)
+	if (props.initial !== false) validateTarget(props.initial)
+	const latest = useRef(props)
+	latest.current = props
+	const state = useRef<{ controller: Controller; host?: any; adapter?: HostAdapter; initialized: boolean } | null>(null)
+	if (!state.current) state.current = { controller: new Controller(clock), initialized: false }
+	const current = state.current
+	const style: Record<string, unknown> = {}
+	const bindings: [MotionKey, number | MotionValue][] = []
+	for (const [key, value] of Object.entries(props.style ?? {})) {
+		if (keys.includes(key as MotionKey)) {
+			if (!(value instanceof MotionValue) && (typeof value !== 'number' || !Number.isFinite(value))) throw new Error(`motion: invalid style ${key}`)
+			if (value instanceof MotionValue && (props.animate?.[key as MotionKey] !== undefined || props.exit?.[key as MotionKey] !== undefined || (props.initial && props.initial[key as MotionKey] !== undefined))) throw new Error(`motion: ${key} has both an animate target and a MotionValue writer`)
+			bindings.push([key as MotionKey, value as number | MotionValue])
+		} else {
+			if (value instanceof MotionValue || ['transform', 'translateX', 'translateY', 'animation', 'transition'].includes(key)) throw new Error(`motion: unsupported or conflicting style ${key}`)
+			style[key] = value
+		}
+	}
+
+	const previous = useRef(bindings)
+	const boundKeys = useRef<MotionKey[]>([])
+	const firstBinding = useRef(true)
+	const firstAnimation = useRef(true)
+	if (previous.current.length !== bindings.length || previous.current.some(([key, value], i) => key !== bindings[i][0] || value !== bindings[i][1])) previous.current = bindings
+	const bind = useRef<(host: any) => void>(() => {})
+	bind.current = (host) => {
+		if (!host) return
+		if (current.host !== host) {
+			current.adapter?.restore()
+			current.host = host
+			current.adapter = attachHost(host)
+			if (!current.initialized) {
+				const baseline = current.adapter.read()
+				for (const [key, value] of previous.current) baseline[key] = value instanceof MotionValue ? value.get() : value
+				current.controller.seed(baseline)
+				current.controller.seed(props.initial === false ? props.animate ?? {} : props.initial ?? {})
+				current.initialized = true
+			}
+
+			current.controller.attach(current.adapter.write)
+		}
+
+		current.controller.flush()
+		latest.current.bind?.(host)
+	}
+
+	const playback = useRef({ transition, reduced })
+	playback.current = { transition, reduced }
+	const returning = useRef<Target | null>(null)
+	const member = useRef<PresenceMember | null>(null)
+	if (!member.current) member.current = {
+		exit() {
+			const snapshot = current.controller.snapshot()
+			returning.current ??= {}
+			for (const key of Object.keys(latest.current.exit ?? {}) as MotionKey[]) {
+				if (!(key in returning.current)) returning.current[key] = snapshot[key]
+			}
+
+			return current.controller.animate(latest.current.exit ?? {}, playback.current.transition, playback.current.reduced)
+		},
+		enter() {
+			const target = { ...returning.current, ...latest.current.animate }
+			returning.current = null
+			void current.controller.animate(target, playback.current.transition, playback.current.reduced).then((result) => {
+				if (result === 'finished' && current.host && presence?.present) latest.current.onAnimationComplete?.()
+			})
+		},
+	}
+
+	useLayoutEffect(() => presence?.register(member.current!), [presence])
+	const stableBind = useRef((host: any) => bind.current(host)).current
+	useLayoutEffect(() => () => { current.controller.destroy(); current.host = undefined; current.adapter = undefined }, [])
+	useLayoutEffect(() => {
+		const off: (() => void)[] = []
+		for (const key of boundKeys.current) if (!previous.current.some(([next]) => key === next)) current.controller.set(key, defaults[key])
+		boundKeys.current = previous.current.map(([key]) => key)
+		for (const [key, value] of previous.current) {
+			if (!firstBinding.current) current.controller.set(key, value instanceof MotionValue ? value.get() : value)
+			if (value instanceof MotionValue) off.push(value.on('change', (next) => current.controller.set(key, next)))
+		}
+
+		firstBinding.current = false
+		return () => off.forEach((unsubscribe) => unsubscribe())
+	}, [previous.current])
+
+	useLayoutEffect(() => {
+		let active = true
+		const skip = firstAnimation.current && props.initial === false
+		firstAnimation.current = false
+		if (presence && !presence.present) presence.restart(member.current!)
+		else if (props.animate && !skip) void current.controller.animate(props.animate, transition, reduced).then((result) => {
+			if (active && result === 'finished') latest.current.onAnimationComplete?.()
+		})
+
+		return () => { active = false; current.controller.stop() }
+	}, [JSON.stringify(props.animate), JSON.stringify(props.exit), JSON.stringify(transition), reduced])
+
+	const { initial, exit, animate, transition: ignoredTransition, onAnimationComplete, style: ignoredStyle, bind: ignoredBind, ...rest } = props
+	return { ...rest, style, bind: stableBind }
+}
+
+/** Animated View preserving the shared primitive's layout and accessibility. */
+export function MotionView(props: MotionViewProps) @{
+	<View {...useMotion(props)}>{props.children}</View>
+}
+
+/** Animated horizontal Row. */
+export function MotionRow(props: MotionRowProps) @{
+	<Row {...useMotion(props)}>{props.children}</Row>
+}
+
+/** Animated Pressable preserving its input callbacks and disabled state. */
+export function MotionPressable(props: MotionPressableProps) @{
+	<Pressable {...useMotion(props)}>{props.children}</Pressable>
+}

package/src/components.web.test.tsrx

@@ -0,0 +1,134 @@
+import { act, createRoot, useEffect } from 'octane'
+import { describe, expect, it, vi } from 'vitest'
+import { motion, MotionConfig, useMotionValue, useTransform, useSpring } from './index.web'
+
+function Box(props: any) @{
+	<motion.View id="box" initial={{ x: 20 }} animate={props.target} transition={{ duration: 0 }} onAnimationComplete={props.done} />
+}
+
+function Values(props: any) @{
+	const x = useMotionValue(2)
+	const doubled = useTransform(x, (value) => value * 2)
+	const spring = useSpring(x)
+	useEffect(() => { props.ready({ x, doubled, spring }) }, [])
+
+	<motion.Row id="values" style={{ x, scaleX: doubled }} />
+}
+
+function Reduced() @{
+	<MotionConfig reducedMotion="always"><motion.Pressable id="reduced" initial={{ x: 0 }} animate={{ x: 100 }} transition={{ duration: 10 }} /></MotionConfig>
+}
+
+function mount(component: any) {
+	const container = document.createElement('div'); document.body.append(container)
+	const root = createRoot(container)
+	act(() => root.render(component))
+	return { container, root, close() { root.unmount(); container.remove() } }
+}
+
+describe('motion hosts', () => {
+	it('updates destinations without remounting and suppresses equal-target restarts', async () => {
+		const done = vi.fn(); const mounted = mount(<Box target={{ x: 50 }} done={done} />)
+		await act(async () => {})
+		const node = mounted.container.querySelector('#box') as HTMLElement
+		expect(node.style.transform).toContain('translateX(50px)')
+		expect(done).toHaveBeenCalledTimes(1)
+		act(() => mounted.root.render(<Box target={{ x: 50 }} done={done} />))
+		await act(async () => {})
+		expect(done).toHaveBeenCalledTimes(1)
+		act(() => mounted.root.render(<Box target={{ x: 80 }} done={done} />))
+		await act(async () => {})
+		expect(mounted.container.querySelector('#box')).toBe(node)
+		expect(node.style.transform).toContain('translateX(80px)')
+		mounted.close()
+	})
+
+	it('binds and derives values without rerender and destroys owned values', () => {
+		let values: any
+		const mounted = mount(<Values ready={(next: any) => { values = next }} />)
+		act(() => values.x.set(10))
+		const node = mounted.container.querySelector('#values') as HTMLElement
+		expect(node.style.transform).toContain('translateX(10px)')
+		expect(node.style.transform).toContain('scaleX(20)')
+		values.spring.jump(7); expect(values.spring.get()).toBe(7)
+		mounted.close()
+		values.x.set(30); expect(values.x.get()).toBe(10)
+	})
+
+	it('reduces transforms through configuration', () => {
+		const mounted = mount(<Reduced />)
+		expect((mounted.container.querySelector('#reduced') as HTMLElement).style.transform).toContain('translateX(100px)')
+		mounted.close()
+	})
+})
+
+function InitialFalse() @{
+	<motion.View id="instant" initial={false} animate={{ x: 25 }} transition={{ duration: 100 }} />
+}
+
+function Binding(props: any) @{
+	<motion.View id="binding" style={props.style} />
+}
+
+function DemoFixture() @{
+	<MotionDemo />
+}
+
+import { MotionDemo } from '../examples/MotionDemo.tsrx'
+import { MotionValue } from './value'
+import { clock } from './clock.web'
+
+describe('binding lifecycle', () => {
+	it('initial=false applies the destination before playback', () => {
+		const mounted = mount(<InitialFalse />)
+		expect((mounted.container.querySelector('#instant') as HTMLElement).style.transform).toContain('translateX(25px)')
+		mounted.close()
+	})
+
+	it('swaps values, removes bindings and preserves independent axes', () => {
+		const x = new MotionValue(10, clock), next = new MotionValue(20, clock)
+		const mounted = mount(<Binding style={{ x, rotate: 30 }} />)
+		const node = mounted.container.querySelector('#binding') as HTMLElement
+		act(() => mounted.root.render(<Binding style={{ x: next, rotate: 30 }} />))
+		x.set(60)
+		expect(node.style.transform).toContain('translateX(20px)')
+		act(() => mounted.root.render(<Binding style={{ rotate: 30 }} />))
+		next.set(80)
+		expect(node.style.transform).toContain('translateX(0px)')
+		expect(node.style.transform).toContain('rotate(30deg)')
+		mounted.close(); x.destroy(); next.destroy()
+	})
+
+	it('mounts the maintained demonstration', () => {
+		const mounted = mount(<DemoFixture />)
+		expect(mounted.container.textContent).toContain('Drag, then release')
+		mounted.close()
+	})
+})
+
+import { signal$ } from 'octane/signals'
+const position$ = signal$(0)
+function SignalBox() @{
+	<motion.View id="signal" animate={{ x: position$.get() }} transition={{ duration: 0 }} />
+}
+
+it('retargets from a render-time signal read', () => {
+	const mounted = mount(<SignalBox />)
+	act(() => position$.set(40))
+	expect((mounted.container.querySelector('#signal') as HTMLElement).style.transform).toContain('translateX(40px)')
+	mounted.close(); position$.set(0)
+})
+
+function UserReduced() @{
+	<MotionConfig reducedMotion="user"><motion.View id="user-reduced" animate={{ x: 100 }} transition={{ duration: 10 }} /></MotionConfig>
+}
+
+it('observes live system reduced-motion changes', () => {
+	let reduced = false
+	const callbacks = new Set<() => void>()
+	vi.stubGlobal('matchMedia', () => ({ get matches() { return reduced }, addEventListener(_type: string, cb: () => void) { callbacks.add(cb) }, removeEventListener(_type: string, cb: () => void) { callbacks.delete(cb) } }))
+	const mounted = mount(<UserReduced />)
+	act(() => { reduced = true; callbacks.forEach((cb) => cb()) })
+	expect((mounted.container.querySelector('#user-reduced') as HTMLElement).style.transform).toContain('translateX(100px)')
+	mounted.close(); expect(callbacks.size).toBe(0); vi.unstubAllGlobals()
+})

package/src/config.tsrx

@@ -0,0 +1,29 @@
+import { createContext, useContext, useEffect, useState } from 'octane'
+import type { MotionConfigProps } from './types'
+import { readReducedMotion, observeReducedMotion } from './reduced-motion'
+
+export const ConfigContext = createContext<MotionConfigProps>({ reducedMotion: 'never' })
+
+/** Observe the live system preference, independent of MotionConfig overrides. */
+export function useReducedMotion(): boolean {
+	const [reduced, setReduced] = useState(readReducedMotion)
+	useEffect(() => {
+		const update = () => setReduced(readReducedMotion())
+		const off = observeReducedMotion(update)
+		update()
+		return off
+	}, [])
+
+	return reduced
+}
+
+/** Inherit transition and reduced-motion defaults within this Octane root. */
+export function MotionConfig(props: MotionConfigProps) @{
+	const parent = useContext(ConfigContext)
+	const value = {
+		transition: props.transition ?? parent.transition,
+		reducedMotion: props.reducedMotion ?? parent.reducedMotion,
+	}
+
+	<ConfigContext value={value}>{props.children}</ConfigContext>
+}

package/src/controller.ts

@@ -0,0 +1,98 @@
+import { MotionValue } from './value'
+import type { Clock } from './clock-types'
+import type { Target, MotionKey, Transition } from './types'
+import type { AnimationResult } from './engine'
+
+export const keys: MotionKey[] = ['opacity', 'x', 'y', 'scale', 'scaleX', 'scaleY', 'rotate']
+export const defaults: Required<Target> = {
+	opacity: 1,
+	x: 0,
+	y: 0,
+	scale: 1,
+	scaleX: 1,
+	scaleY: 1,
+	rotate: 0,
+}
+
+export function validateTarget(target?: Target) {
+	for (const [key, value] of Object.entries(target ?? {})) {
+		if (!keys.includes(key as MotionKey) || !Number.isFinite(value)) {
+			throw new Error(`motion: unsupported target ${key}; expected a finite numeric motion channel`)
+		}
+	}
+}
+
+export class Controller {
+	readonly values = new Map<MotionKey, MotionValue>()
+	private write?: (target: Target) => void
+	private generation = 0
+	constructor(private clock: Clock) {}
+	private value(key: MotionKey) {
+		let value = this.values.get(key)
+		if (!value) {
+			value = new MotionValue(defaults[key], this.clock)
+			this.values.set(key, value)
+			value.on('change', () => this.flush())
+		}
+
+		return value
+	}
+	attach(write: (target: Target) => void) {
+		this.write = write
+		this.flush()
+	}
+	snapshot(): Target {
+		return Object.fromEntries([...this.values].map(([key, value]) => [key, value.get()]))
+	}
+	flush() {
+		this.write?.(Object.fromEntries([...this.values].map(([key, value]) => [key, value.get()])))
+	}
+	set(key: MotionKey, next: number) {
+		this.value(key).jump(next)
+	}
+	seed(target: Target) {
+		validateTarget(target)
+		for (const [key, value] of Object.entries(target)) {
+			this.set(key as MotionKey, value)
+		}
+	}
+	async animate(
+		target: Target,
+		transition: Transition,
+		reduced: boolean,
+	): Promise<AnimationResult> {
+		validateTarget(target)
+		const generation = ++this.generation
+		// A new destination owns the entire declarative animation, including removed keys.
+		for (const value of this.values.values()) {
+			value.stop('replaced')
+		}
+
+		const jobs = Object.entries(target).map(([key, to]) => {
+			const value = this.value(key as MotionKey)
+			return value.animate(to, reduced && key !== 'opacity' ? { duration: 0 } : transition).finished
+		})
+
+		const results = await Promise.all(jobs)
+		if (generation !== this.generation) {
+			return 'replaced'
+		}
+
+		return results.every((result) => result === 'finished') ? 'finished' : 'cancelled'
+	}
+	stop() {
+		++this.generation
+		for (const value of this.values.values()) {
+			value.stop()
+		}
+	}
+	destroy() {
+		this.stop()
+		for (const value of this.values.values()) {
+			value.destroy()
+		}
+
+		this.values.clear()
+		this.write = undefined
+	}
+}