@octane-xplat/motion 0.0.0 → 0.7.1

package/src/presence.web.test.tsrx

@@ -0,0 +1,122 @@
+import { act, createRoot, useEffect, useState } from 'octane'
+import { describe, expect, it, vi } from 'vitest'
+import { motion, Presence, MotionConfig } from './index.web'
+
+let mounts = 0, cleanups = 0
+function Child(props: any) @{
+	const [count, setCount] = useState(0)
+	useEffect(() => { mounts++; return () => { cleanups++ } }, [])
+
+	<motion.View id="exiting" initial={false} animate={{ x: 0 }} exit={{ x: 100 }} transition={{ duration: props.duration }}>
+		<button id="counter" onClick={() => setCount(count + 1)}>{count}</button>
+	</motion.View>
+}
+
+function Scene(props: any) @{
+	<MotionConfig reducedMotion={props.reduced ? 'always' : 'never'}>
+		<Presence present={props.present} onExitComplete={props.done} id="boundary">
+			<Child duration={props.duration ?? 0.1} />
+		</Presence>
+	</MotionConfig>
+}
+
+function mount(props: any) {
+	const container = document.createElement('div'); document.body.append(container)
+	const root = createRoot(container)
+	act(() => root.render(<Scene {...props} />))
+	return { container, root, update(next: any) { act(() => root.render(<Scene {...next} />)) }, close() { act(() => root.unmount()); container.remove() } }
+}
+
+const advance = async (ms: number) => { await act(async () => { await vi.advanceTimersByTimeAsync(ms) }) }
+
+describe('retained presence', () => {
+	it('retains component state until exit finishes, blocks input and relinquishes focus', async () => {
+		vi.useFakeTimers(); mounts = cleanups = 0
+		const done = vi.fn(); const r = mount({ present: true, done })
+		const node = r.container.querySelector('#exiting')
+		const button = r.container.querySelector('button') as HTMLButtonElement
+		act(() => button.click()); button.focus()
+		expect(button.textContent).toBe('1')
+		r.update({ present: false, done })
+		expect(r.container.querySelector('#exiting')).toBe(node)
+		expect(cleanups).toBe(0)
+		expect(r.container.querySelector('#boundary')?.hasAttribute('inert')).toBe(true)
+		expect(document.activeElement).not.toBe(button)
+		await advance(160)
+		expect(r.container.querySelector('#exiting')).toBeNull()
+		expect(cleanups).toBe(1); expect(done).toHaveBeenCalledTimes(1)
+		r.close(); vi.useRealTimers()
+	})
+
+	it('reverses without remounting or stale removal', async () => {
+		vi.useFakeTimers(); mounts = cleanups = 0
+		const done = vi.fn(); const r = mount({ present: true, done })
+		const node = r.container.querySelector('#exiting')
+		r.update({ present: false, done }); await advance(32)
+		r.update({ present: true, done }); await advance(200)
+		expect(r.container.querySelector('#exiting')).toBe(node)
+		expect(mounts).toBe(1); expect(cleanups).toBe(0)
+		expect(done).not.toHaveBeenCalled()
+		expect(r.container.querySelector('#boundary')?.hasAttribute('inert')).toBe(false)
+		r.close(); expect(cleanups).toBe(1); vi.useRealTimers()
+	})
+
+	it('disposes immediately when the boundary unmounts', async () => {
+		vi.useFakeTimers(); mounts = cleanups = 0
+		const done = vi.fn(); const r = mount({ present: true, done })
+		r.update({ present: false, done }); r.close()
+		expect(cleanups).toBe(1)
+		await advance(200); expect(done).not.toHaveBeenCalled()
+		vi.useRealTimers()
+	})
+
+	it('starts absent, supports repeated cycles and instant reduced exits', async () => {
+		vi.useFakeTimers(); mounts = cleanups = 0
+		const done = vi.fn(); const r = mount({ present: false, done, reduced: true })
+		expect(r.container.querySelector('#exiting')).toBeNull()
+		for (let i = 0; i < 2; i++) {
+			r.update({ present: true, done, reduced: true }); await advance(1)
+			expect(r.container.querySelector('#exiting')).not.toBeNull()
+			r.update({ present: false, done, reduced: true }); await advance(1)
+			expect(r.container.querySelector('#exiting')).toBeNull()
+		}
+
+		expect(done).toHaveBeenCalledTimes(2)
+		r.close(); vi.useRealTimers()
+	})
+})
+
+import { PresenceDemo } from '../examples/PresenceDemo.tsrx'
+it('mounts the retained-presence example', () => {
+	const container = document.createElement('div'); document.body.append(container)
+	const root = createRoot(container)
+	act(() => root.render(<PresenceDemo />))
+	expect(container.textContent).toContain('Count: 0')
+	act(() => root.unmount()); container.remove()
+})
+
+import { useMotionValue } from './index.web'
+function Independent(props: any) @{
+	const x = useMotionValue(0)
+	useEffect(() => { props.ready(x) }, [])
+
+	<Presence present={props.present}>
+		<motion.View id="independent" style={{ x }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} transition={{ duration: 0.1 }} />
+	</Presence>
+}
+
+it('exit reversal does not take ownership of independent MotionValue channels', async () => {
+	vi.useFakeTimers()
+	let x: any
+	const ready = (value: any) => { x = value }
+	const container = document.createElement('div'); document.body.append(container)
+	const root = createRoot(container)
+	act(() => root.render(<Independent present={true} ready={ready} />))
+	act(() => root.render(<Independent present={false} ready={ready} />))
+	await advance(32)
+	x.set(50)
+	act(() => root.render(<Independent present={true} ready={ready} />))
+	await advance(200)
+	expect((container.querySelector('#independent') as HTMLElement).style.transform).toContain('translateX(50px)')
+	act(() => root.unmount()); container.remove(); vi.useRealTimers()
+})

package/src/reduced-motion.ts

@@ -0,0 +1,37 @@
+import { Application, Utils } from '@nativescript/core'
+
+export function readReducedMotion(): boolean {
+	const platform = globalThis as any
+	if (Application.ios) {
+		return Boolean(platform.UIAccessibilityIsReduceMotionEnabled?.())
+	}
+
+	const context = Utils.android.getApplicationContext()
+	return (
+		platform.android.provider.Settings.Global.getFloat(
+			context.getContentResolver(),
+			'animator_duration_scale',
+			1,
+		) === 0
+	)
+}
+
+// Poll only while subscribed; this also detects Android developer-setting changes
+// without owning a Java ContentObserver class. Resume refreshes immediately.
+export function observeReducedMotion(notify: () => void): () => void {
+	let previous = readReducedMotion()
+	const check = () => {
+		const next = readReducedMotion()
+		if (next !== previous) {
+			previous = next
+			notify()
+		}
+	}
+
+	const timer = setInterval(check, 500)
+	Application.on(Application.resumeEvent, check)
+	return () => {
+		clearInterval(timer)
+		Application.off(Application.resumeEvent, check)
+	}
+}

package/src/reduced-motion.web.ts

@@ -0,0 +1,13 @@
+export function readReducedMotion(): boolean {
+	return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches
+}
+
+export function observeReducedMotion(notify: () => void): () => void {
+	if (typeof matchMedia !== 'function') {
+		return () => {}
+	}
+
+	const media = matchMedia('(prefers-reduced-motion: reduce)')
+	media.addEventListener('change', notify)
+	return () => media.removeEventListener('change', notify)
+}

package/src/types.ts

@@ -0,0 +1,55 @@
+import type { ViewProps, RowProps, PressableProps } from '@octane-xplat/ui'
+import type { MotionValue } from './value'
+
+/** Supported channels. Translation is CSS pixels/DIP; rotation is degrees. */
+export type MotionKey = 'opacity' | 'x' | 'y' | 'scale' | 'scaleX' | 'scaleY' | 'rotate'
+/** Absolute numeric destinations; omitted channels retain their current values. */
+export type Target = Partial<Record<MotionKey, number>>
+/** Tween easing, including a CSS-compatible cubic Bezier tuple. */
+export type Ease = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | [number, number, number, number]
+/** Timing is seconds. Spring velocity is units per second. */
+export interface Transition {
+	type?: 'tween' | 'spring'
+	duration?: number
+	delay?: number
+	ease?: Ease
+	stiffness?: number
+	damping?: number
+	mass?: number
+	velocity?: number
+	restSpeed?: number
+	restDelta?: number
+}
+
+/** Static platform styles plus numeric motion-value bindings. */
+export type MotionStyle = Record<string, unknown> & Partial<Record<MotionKey, number | MotionValue>>
+/** Supported declarative motion controls. */
+export interface MotionProps {
+	initial?: Target | false
+	/** Destination while the nearest Presence boundary retains this host for exit. */
+	exit?: Target
+	animate?: Target
+	transition?: Transition
+	style?: MotionStyle
+	onAnimationComplete?: () => void
+}
+
+/** View layout and accessibility props with motion controls. */
+export type MotionViewProps = Omit<ViewProps, 'style'> & MotionProps
+/** Row layout and accessibility props with motion controls. */
+export type MotionRowProps = Omit<RowProps, 'style'> & MotionProps
+/** Pressable interaction props with motion controls. */
+export type MotionPressableProps = Omit<PressableProps, 'style'> & MotionProps
+/** Inherited defaults; `user` observes the live system preference. */
+export interface MotionConfigProps {
+	transition?: Transition
+	reducedMotion?: 'always' | 'never' | 'user'
+	children?: any
+}
+
+/** Presence renders a View wrapper; use its layout props to size retained content. */
+export interface PresenceProps extends ViewProps {
+	present: boolean
+	/** Called once after all registered exits finish, never after reversal/disposal. */
+	onExitComplete?: () => void
+}

package/src/value.ts

@@ -0,0 +1,167 @@
+import type { Clock } from './clock-types'
+import type { Transition } from './types'
+import { runAnimation, validateTransition, type AnimationControls } from './engine'
+
+/** Events supported by numeric motion values. */
+export interface MotionValueEvents {
+	change: (value: number) => void
+	animationStart: () => void
+	animationComplete: () => void
+	animationCancel: () => void
+	destroy: () => void
+}
+
+/** Numeric value with direct subscriptions; it does not subscribe Octane renders. */
+export class MotionValue {
+	private current: number
+	private previous: number
+	private velocity = 0
+	private updated: number
+	private controls?: AnimationControls
+	private generation = 0
+	private listeners = new Map<keyof MotionValueEvents, Set<Function>>()
+	private passive?: (value: number) => void
+	private disposed = false
+	constructor(
+		initial: number,
+		private clock: Clock,
+	) {
+		this.assert(initial)
+		this.current = this.previous = initial
+		this.updated = clock.now()
+	}
+	private assert(value: number) {
+		if (!Number.isFinite(value)) {
+			throw new Error('motion: values must be finite numbers')
+		}
+	}
+	/** Read the current sample. */
+	get() {
+		return this.current
+	}
+	/** Read the previous sample. */
+	getPrevious() {
+		return this.previous
+	}
+	/** Velocity in units per second; stale samples have zero velocity. */
+	getVelocity() {
+		return this.clock.now() - this.updated > 30 ? 0 : this.velocity
+	}
+	/** Set immediately, or animate when this is a useSpring value. */
+	set(value: number) {
+		this.assert(value)
+		if (this.disposed) {
+			return
+		}
+
+		if (this.passive) {
+			this.passive(value)
+		} else {
+			this.stop()
+			this.write(value)
+		}
+	}
+	/** Snap and stop current playback, resetting velocity. */
+	jump(value: number) {
+		this.assert(value)
+		this.stop()
+		this.write(value)
+		this.velocity = 0
+	}
+	/** Subscribe without causing a component render. Returns an unsubscribe function. */
+	on<K extends keyof MotionValueEvents>(event: K, callback: MotionValueEvents[K]): () => void {
+		let listeners = this.listeners.get(event)
+		if (!listeners) {
+			this.listeners.set(event, (listeners = new Set()))
+		}
+
+		listeners.add(callback)
+		return () => {
+			listeners.delete(callback)
+		}
+	}
+	private emit(event: keyof MotionValueEvents, value?: number) {
+		// Snapshot because subscribers may unsubscribe or add listeners while notified.
+		// eslint-disable-next-line unicorn/no-useless-spread
+		for (const callback of [...(this.listeners.get(event) ?? [])]) {
+			callback(value)
+		}
+	}
+	private write(value: number) {
+		if (this.disposed) {
+			return
+		}
+
+		const now = this.clock.now()
+		const elapsed = now - this.updated
+		if (elapsed > 0) {
+			this.velocity = elapsed > 30 ? 0 : ((value - this.current) * 1000) / elapsed
+		}
+
+		this.previous = this.current
+		this.current = value
+		this.updated = now
+		if (value !== this.previous) {
+			this.emit('change', value)
+		}
+	}
+	/** Animate to a destination. New playback replaces old playback. */
+	animate(target: number, transition: Transition = {}): AnimationControls {
+		this.assert(target)
+		validateTransition(transition)
+		if (this.disposed) {
+			return { finished: Promise.resolve('cancelled'), stop() {} }
+		}
+
+		const velocity = transition.velocity ?? this.getVelocity()
+		this.stop('replaced')
+		const generation = ++this.generation
+		this.emit('animationStart')
+		const controls = runAnimation(
+			this.clock,
+			this.current,
+			target,
+			{ ...transition, velocity },
+			(value) => this.write(value),
+		)
+
+		this.controls = controls
+		void controls.finished.then((result) => {
+			if (generation !== this.generation || this.disposed) {
+				return
+			}
+
+			this.controls = undefined
+			if (result === 'finished') {
+				this.emit('animationComplete')
+			}
+		})
+
+		return controls
+	}
+	/** Stop playback at its current value. */
+	stop(reason: 'cancelled' | 'replaced' = 'cancelled') {
+		++this.generation
+		if (this.controls) {
+			this.controls.stop(reason)
+			this.controls = undefined
+			this.emit('animationCancel')
+		}
+	}
+	/** Release playback and listeners when the owning component unmounts. */
+	destroy() {
+		this.stop()
+		this.emit('destroy')
+		this.listeners.clear()
+		this.passive = undefined
+		this.disposed = true
+	}
+	/** @internal Install the useSpring setter interception. */
+	attach(setter: (value: number) => void) {
+		this.passive = setter
+		return () => {
+			this.passive = undefined
+			this.stop()
+		}
+	}
+}

package/types/clock-types.d.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/types/engine.d.ts

@@ -0,0 +1,11 @@
+import type { Clock } from './clock-types';
+import type { Transition } from './types';
+/** Terminal status; cancellation never masquerades as completion. */
+export type AnimationResult = 'finished' | 'cancelled' | 'replaced';
+/** A cancellable animation whose finished promise always settles. */
+export interface AnimationControls {
+    finished: Promise<AnimationResult>;
+    stop(reason?: Exclude<AnimationResult, 'finished'>): void;
+}
+export declare function validateTransition(t: Transition): void;
+export declare function runAnimation(clock: Clock, from: number, to: number, transition: Transition, update: (value: number) => void, complete?: () => void): AnimationControls;

package/types/index.d.ts

@@ -0,0 +1,53 @@
+import type { UniversalComponent } from 'octane/universal'
+import type {
+	MotionViewProps,
+	MotionRowProps,
+	MotionPressableProps,
+	MotionConfigProps,
+	Transition,
+} from './types'
+import type { MotionValue, MotionValueEvents } from './value'
+/** Bounded motion hosts for shared xplat UI primitives. */
+export declare const motion: {
+	View: UniversalComponent<MotionViewProps>
+	Row: UniversalComponent<MotionRowProps>
+	Pressable: UniversalComponent<MotionPressableProps>
+}
+/** Inherit transition and reduced-motion defaults within this root. */
+export declare const MotionConfig: UniversalComponent<MotionConfigProps>
+/** Observe the live system reduced-motion preference. */
+export declare function useReducedMotion(): boolean
+/** Create an owned numeric value; writes do not render components. */
+export declare function useMotionValue(initial: number): MotionValue
+/** Subscribe to an event until replacement or unmount. */
+export declare function useMotionValueEvent<K extends keyof MotionValueEvents>(
+	value: MotionValue,
+	event: K,
+	callback: MotionValueEvents[K],
+): void
+/** Derive a numeric value by mapping ranges or transforming source samples. */
+export declare function useTransform(
+	source: MotionValue,
+	input: number[],
+	output: number[],
+	options?: { clamp?: boolean },
+): MotionValue
+export declare function useTransform(
+	source: MotionValue,
+	transform: (value: number) => number,
+): MotionValue
+export declare function useTransform(
+	source: MotionValue[],
+	transform: (values: number[]) => number,
+): MotionValue
+/** Spring toward set targets or a source MotionValue; jump snaps. */
+export declare function useSpring(
+	source: number | MotionValue,
+	options?: Omit<Transition, 'type' | 'duration' | 'ease' | 'delay'>,
+): MotionValue
+export type { MotionValue, MotionValueEvents }
+export type { AnimationControls, AnimationResult } from './engine'
+export type * from './types'
+
+/** Retain live children through exit; removing the boundary disposes immediately. */
+export declare const Presence: UniversalComponent<import('./types').PresenceProps>

package/types/types.d.ts

@@ -0,0 +1,51 @@
+import type { ViewProps, RowProps, PressableProps } from '@octane-xplat/ui';
+import type { MotionValue } from './value';
+/** Supported channels. Translation is CSS pixels/DIP; rotation is degrees. */
+export type MotionKey = 'opacity' | 'x' | 'y' | 'scale' | 'scaleX' | 'scaleY' | 'rotate';
+/** Absolute numeric destinations; omitted channels retain their current values. */
+export type Target = Partial<Record<MotionKey, number>>;
+/** Tween easing, including a CSS-compatible cubic Bezier tuple. */
+export type Ease = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | [number, number, number, number];
+/** Timing is seconds. Spring velocity is units per second. */
+export interface Transition {
+    type?: 'tween' | 'spring';
+    duration?: number;
+    delay?: number;
+    ease?: Ease;
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    velocity?: number;
+    restSpeed?: number;
+    restDelta?: number;
+}
+/** Static platform styles plus numeric motion-value bindings. */
+export type MotionStyle = Record<string, unknown> & Partial<Record<MotionKey, number | MotionValue>>;
+/** Supported declarative motion controls. */
+export interface MotionProps {
+    initial?: Target | false;
+    /** Destination while the nearest Presence boundary retains this host for exit. */
+    exit?: Target;
+    animate?: Target;
+    transition?: Transition;
+    style?: MotionStyle;
+    onAnimationComplete?: () => void;
+}
+/** View layout and accessibility props with motion controls. */
+export type MotionViewProps = Omit<ViewProps, 'style'> & MotionProps;
+/** Row layout and accessibility props with motion controls. */
+export type MotionRowProps = Omit<RowProps, 'style'> & MotionProps;
+/** Pressable interaction props with motion controls. */
+export type MotionPressableProps = Omit<PressableProps, 'style'> & MotionProps;
+/** Inherited defaults; `user` observes the live system preference. */
+export interface MotionConfigProps {
+    transition?: Transition;
+    reducedMotion?: 'always' | 'never' | 'user';
+    children?: any;
+}
+/** Presence renders a View wrapper; use its layout props to size retained content. */
+export interface PresenceProps extends ViewProps {
+    present: boolean;
+    /** Called once after all registered exits finish, never after reversal/disposal. */
+    onExitComplete?: () => void;
+}

package/types/value.d.ts

@@ -0,0 +1,48 @@
+import type { Clock } from './clock-types';
+import type { Transition } from './types';
+import { type AnimationControls } from './engine';
+/** Events supported by numeric motion values. */
+export interface MotionValueEvents {
+    change: (value: number) => void;
+    animationStart: () => void;
+    animationComplete: () => void;
+    animationCancel: () => void;
+    destroy: () => void;
+}
+/** Numeric value with direct subscriptions; it does not subscribe Octane renders. */
+export declare class MotionValue {
+    private clock;
+    private current;
+    private previous;
+    private velocity;
+    private updated;
+    private controls?;
+    private generation;
+    private listeners;
+    private passive?;
+    private disposed;
+    constructor(initial: number, clock: Clock);
+    private assert;
+    /** Read the current sample. */
+    get(): number;
+    /** Read the previous sample. */
+    getPrevious(): number;
+    /** Velocity in units per second; stale samples have zero velocity. */
+    getVelocity(): number;
+    /** Set immediately, or animate when this is a useSpring value. */
+    set(value: number): void;
+    /** Snap and stop current playback, resetting velocity. */
+    jump(value: number): void;
+    /** Subscribe without causing a component render. Returns an unsubscribe function. */
+    on<K extends keyof MotionValueEvents>(event: K, callback: MotionValueEvents[K]): () => void;
+    private emit;
+    private write;
+    /** Animate to a destination. New playback replaces old playback. */
+    animate(target: number, transition?: Transition): AnimationControls;
+    /** Stop playback at its current value. */
+    stop(reason?: 'cancelled' | 'replaced'): void;
+    /** Release playback and listeners when the owning component unmounts. */
+    destroy(): void;
+    /** @internal Install the useSpring setter interception. */
+    attach(setter: (value: number) => void): () => void;
+}