@octane-xplat/lottie 0.0.1 → 0.10.0

package/src/Lottie.tsrx

@@ -0,0 +1,162 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useImperativeHandle, useCallback, useEffect, useRef } from 'octane';
+import { registerElement } from '@nativescript-community/octane';
+import { isAndroid } from '@nativescript/core';
+import { LottieView } from './vendor/ui-lottie/src/lottie';
+import type { LottieHandle, LottieProps } from './props';
+import { cx } from './cx.mobile';
+import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from './escape-props';
+import { layoutChildProps } from './layout-child';
+
+registerElement('xplatlottie', LottieView);
+
+const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
+
+const STRETCH: Record<string, string> = {
+	contain: 'aspectFit',
+	cover: 'aspectFill',
+	fill: 'fill',
+};
+
+/** Duration in ms on both platforms — the plugin's `duration` reports
+ *  seconds on iOS and ms on Android. */
+function durationMs(v: LottieView): number {
+	const d = v.duration ?? 0;
+	return isAndroid ? d : Math.max(0, d) * 1000;
+}
+
+function currentProgress(v: LottieView): number {
+	// the native type is platform-divergent (LottieAnimationView vs
+	// CompatibleAnimationView) — runtime branch is the narrowing.
+	const nv = v.nativeViewProtected as any;
+	return isAndroid ? (nv?.getProgress?.() ?? 0) : (nv?.currentProgress ?? 0);
+}
+
+/** Stop = pause + reset playhead. iOS `stop()` resets to the start;
+ *  Android's `cancelAnimation()` ends the animator and the next
+ *  `playAnimation()` restarts from 0. */
+function stopView(v: LottieView) {
+	if (isAndroid) v.cancelAnimation();
+	else v.nativeViewProtected?.stop();
+
+	v.progress = 0;
+}
+
+/** Lottie — vendored ui-lottie surface (see src/plugin). The plugin
+ *  doesn't diff props, so src/play-state/speed/progress land imperatively
+ *  in effects. `async` stays forced on: it keeps the load path uniform
+ *  (one code path for inline/file/URL/.lottie) and avoids main-thread
+ *  parse jank; autoPlay is re-applied when the composition lands. */
+export function Lottie(props: LottieProps) @{
+	const host = useRef<LottieView | null>(null);
+	const appliedSrc = useRef<string | undefined>(undefined);
+	const loadedRef = useRef(false);
+
+	useImperativeHandle(props.ref, () => handle(host.current!), []);
+
+	const bindHost = useCallback((v: LottieView) => {
+		host.current = v;
+	}, []);
+
+	const wantPlay = () => props.playing ?? props.autoPlay ?? true;
+
+	const onReady = () => {
+		const v = host.current;
+		if (!v || loadedRef.current) return;
+		loadedRef.current = true;
+		if (props.speed !== undefined) v.speed = props.speed;
+		if (props.progress !== undefined) v.progress = clamp01(props.progress);
+		props.onLoaded?.({ duration: durationMs(v) });
+		if (wantPlay() && !v.isAnimating()) v.playAnimation();
+	};
+
+	// Mount wiring — events first so a synchronous src assignment can't
+	// race past them.
+	useEffect(() => {
+		const v = host.current;
+		if (!v) return;
+		applyEscapeProps(v, props);
+		v.stretch = STRETCH[props.fit ?? 'contain'] as any;
+		v.async = true;
+
+		v.on(LottieView.compositionLoadedEvent, () => onReady());
+		v.on(LottieView.loadFailedEvent, (e: any) => {
+			loadedRef.current = false;
+			props.onError?.({ message: e?.error ? String(e.error) : 'load failed' });
+		});
+
+		// The vendored fix reports a single `false` on cancel — only a
+		// `true` finish reaches onEnded.
+		v.completionBlock = (finished: boolean) => {
+			if (finished) props.onEnded?.();
+		};
+
+	}, []);
+
+	// src — applied imperatively after the listeners exist.
+	useEffect(() => {
+		const v = host.current;
+		if (!v) return;
+		const src = props.data ? JSON.stringify(props.data) : props.src;
+		if (src === appliedSrc.current) return;
+		appliedSrc.current = src;
+		loadedRef.current = false;
+		v.src = src ?? '';
+	}, [props.src, props.data]);
+
+	// Controlled `playing` — play state is a method call, not a prop.
+	useEffect(() => {
+		const v = host.current;
+		if (!v || props.playing === undefined) return;
+		if (props.playing) {
+			if (loadedRef.current) v.resumeAnimation();
+			// not loaded yet — onReady picks it up via wantPlay()
+		} else {
+			v.pauseAnimation();
+		}
+	}, [props.playing]);
+
+	useEffect(() => {
+		const v = host.current;
+		if (!v || props.progress === undefined || !loadedRef.current) return;
+		v.progress = clamp01(props.progress);
+	}, [props.progress]);
+
+	useEffect(() => {
+		const v = host.current;
+		if (!v || props.speed === undefined || !loadedRef.current) return;
+		v.speed = props.speed;
+	}, [props.speed]);
+
+	const handle = (v: LottieView): LottieHandle => ({
+		play: () => v.resumeAnimation(),
+		pause: () => v.pauseAnimation(),
+		stop: () => stopView(v),
+		seekTo: (p: number) => {
+			v.progress = clamp01(p);
+		},
+		setSpeed: (n: number) => {
+			v.speed = n;
+		},
+		progress: () => currentProgress(v),
+		duration: () => durationMs(v),
+		isPlaying: () => v.isAnimating(),
+		native: v,
+	});
+
+	<xplatlottie
+		ref={bindHost}
+		id={props.id}
+		className={cx(props.className)}
+		style={props.style}
+		{...layoutChildProps(props)}
+		loop={props.loop ?? false}
+		accessible={props.accessible}
+		accessibilityLabel={props.accessibilityLabel}
+		accessibilityRole={nativeAccessibilityRole(props.accessibilityRole) as any}
+		accessibilityHint={props.accessibilityHint}
+		accessibilityValue={props.accessibilityValue}
+		accessibilityState={nativeAccessibilityState(props.accessibilityState) as any}
+		accessibilityLiveRegion={props.accessibilityLiveRegion as any}
+	/>
+}

package/src/Lottie.web.tsrx

@@ -0,0 +1,152 @@
+import lottie, { type AnimationItem } from 'lottie-web';
+import { useState, useImperativeHandle, useEffect, useRef } from 'octane';
+import type { LottieHandle, LottieProps } from './props';
+import { applyEscapeProps } from './escape-props.web';
+import { layoutChildProps } from './layout-child.web';
+
+const PRESERVE: Record<string, string> = {
+	contain: 'xMidYMid meet',
+	cover: 'xMidYMid slice',
+	fill: 'none',
+};
+
+const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
+
+/** Lottie — lottie-web's svg renderer in a plain container div. Everything
+ *  is imperative: `src`/`data` rebuild the AnimationItem, the rest are
+ *  method calls applied in effects. Progress is normalized 0..1
+ *  (lottie-web speaks frames); durations arrive in seconds and are
+ *  surfaced as ms. */
+export function Lottie(props: LottieProps) @{
+	const [animation, setAnimation] = useState<AnimationItem | null>(null);
+	const el = useRef<HTMLDivElement | null>(null);
+	const anim = useRef<AnimationItem | null>(null);
+	const ready = useRef(false);
+
+	const wantPlay = () => props.playing ?? props.autoPlay ?? true;
+
+	const build = (host: HTMLDivElement) => {
+		anim.current?.destroy();
+		anim.current = null;
+		setAnimation(null);
+		ready.current = false;
+
+		let animationData: object | undefined;
+		try {
+			animationData = props.data ?? (props.src?.startsWith('{') ? JSON.parse(props.src) : undefined);
+		} catch (error) {
+			props.onError?.({ message: error instanceof Error ? error.message : String(error) });
+			return;
+		}
+
+		const path = animationData ? undefined : props.src;
+		if (!animationData && !path) return;
+
+		let a: AnimationItem;
+		try {
+			a = lottie.loadAnimation({
+				container: host,
+				renderer: 'svg',
+				loop: props.loop ?? false,
+				autoplay: false, // leaf owns play state — uniform with native
+				animationData,
+				path,
+				rendererSettings: { preserveAspectRatio: PRESERVE[props.fit ?? 'contain'] },
+		});
+		} catch (error) {
+			props.onError?.({ message: error instanceof Error ? error.message : String(error) });
+			return;
+		}
+
+		anim.current = a;
+		setAnimation(a);
+
+		a.addEventListener('DOMLoaded', () => {
+			ready.current = true;
+			if (props.speed !== undefined) a.setSpeed(props.speed);
+			if (props.progress !== undefined) seekTo(props.progress);
+			props.onLoaded?.({ duration: a.getDuration() * 1000 });
+			if (wantPlay()) a.play();
+		});
+
+		a.addEventListener('complete', () => props.onEnded?.());
+		a.addEventListener('data_failed', () => props.onError?.({ message: 'animation data failed to load' }));
+		a.addEventListener('error', () => props.onError?.({ message: 'animation failed' }));
+	};
+
+	const seekTo = (p: number) => {
+		const a = anim.current;
+		if (!a) return;
+		const frame = clamp01(p) * a.totalFrames;
+		// goToAndStop parks the playhead — keep playing state instead.
+		if (a.isPaused) a.goToAndStop(frame, true);
+		else a.goToAndPlay(frame, true);
+	};
+
+	// Build once the container exists; rebuild on src/data/fit changes.
+	useEffect(() => {
+		const host = el.current;
+		if (!host) return;
+		build(host);
+		return () => {
+			anim.current?.destroy();
+			anim.current = null;
+			ready.current = false;
+		};
+	}, [props.src, props.data, props.fit]);
+
+	useEffect(() => {
+		if (props.loop !== undefined && anim.current) {
+			anim.current.loop = props.loop;
+		}
+	}, [props.loop]);
+
+	useEffect(() => {
+		if (props.playing === undefined || !anim.current || !ready.current) return;
+		if (props.playing) anim.current.play();
+		else anim.current.pause();
+	}, [props.playing]);
+
+	useEffect(() => {
+		if (props.progress === undefined) return;
+		seekTo(props.progress);
+	}, [props.progress]);
+
+	useEffect(() => {
+		if (props.speed !== undefined) anim.current?.setSpeed(props.speed);
+	}, [props.speed]);
+
+	const handle = (a: AnimationItem): LottieHandle => ({
+		play: () => a.play(),
+		pause: () => a.pause(),
+		stop: () => a.stop(),
+		seekTo,
+		setSpeed: (n: number) => a.setSpeed(n),
+		progress: () => (a.totalFrames ? a.currentRawFrame / a.totalFrames : 0),
+		duration: () => a.getDuration() * 1000,
+		isPlaying: () => !a.isPaused,
+		native: a,
+	});
+
+	useImperativeHandle<LottieHandle | null>(props.ref, () => animation ? handle(animation) : null, [animation]);
+
+	<div
+		ref={(v: HTMLDivElement | null) => {
+			el.current = v;
+			if (!v) return;
+			applyEscapeProps(v, props);
+		}}
+		id={props.id}
+		className={props.className}
+		{...layoutChildProps(props, props.style)}
+		role={props.accessibilityRole ?? 'img'}
+		aria-label={props.accessibilityLabel}
+		aria-hidden={props.accessible === false ? true : undefined}
+		aria-description={props.accessibilityHint}
+		aria-valuetext={props.accessibilityValue}
+		aria-disabled={props.accessibilityState?.disabled}
+		aria-selected={props.accessibilityState?.selected}
+		aria-checked={props.accessibilityState?.checked}
+		aria-live={props.accessibilityLiveRegion === 'none' ? 'off' : props.accessibilityLiveRegion}
+	/>
+}

package/src/cx.mobile.ts

@@ -0,0 +1,8 @@
+/** NS `className` splits on ' ' only, and the universal driver applies the
+ *  prop via `String(value)` — an array would arrive comma-joined and match
+ *  no class at all. Native leaves normalize through cx() before handing
+ *  className to an intrinsic. (The DOM renderer already flattens arrays,
+ *  so web leaves don't need this.) */
+export function cx(...parts: any[]): string {
+	return parts.flat(Infinity).filter(Boolean).join(' ')
+}

package/src/escape-props.ts

@@ -0,0 +1,65 @@
+import { isAndroid, isIOS } from '@nativescript/core'
+import type { Role } from './props'
+
+/** Apply only the active device's escape bag after the primitive's own props. */
+export function applyEscapeProps(view: any, props: { ios?: any; android?: any }): void {
+	if (!view) {
+		return
+	}
+
+	const bag = isIOS ? props.ios : isAndroid ? props.android : undefined
+	if (bag) {
+		Object.assign(view, bag)
+	}
+}
+
+const NATIVE_ACCESSIBILITY_ROLES: Record<Role, string> = {
+	button: 'button',
+	link: 'link',
+	search: 'search',
+	image: 'image',
+	heading: 'header',
+	adjustable: 'adjustable',
+	summary: 'summary',
+	text: 'text',
+	none: 'none',
+	progressbar: 'progressBar',
+	checkbox: 'checkbox',
+	switch: 'switch',
+	radio: 'radioButton',
+	spinbutton: 'spinButton',
+	// NativeScript has no tab role; a tab is still an actionable button and
+	// its selected state is carried separately by accessibilityState.
+	tab: 'button',
+}
+
+/** Translate the shared/ARIA spelling to NativeScript's narrower role enum. */
+export function nativeAccessibilityRole(role?: Role): string | undefined {
+	return role ? NATIVE_ACCESSIBILITY_ROLES[role] : undefined
+}
+
+/** NativeScript's AccessibilityState is a single enum value, unlike the
+ *  web's independent ARIA booleans. Priority follows the strongest state. */
+export function nativeAccessibilityState(state?: {
+	disabled?: boolean
+	selected?: boolean
+	checked?: boolean
+}): string | undefined {
+	if (state?.disabled) {
+		return 'disabled'
+	}
+
+	if (state?.selected) {
+		return 'selected'
+	}
+
+	if (state?.checked === true) {
+		return 'checked'
+	}
+
+	if (state?.checked === false) {
+		return 'unchecked'
+	}
+
+	return undefined
+}

package/src/escape-props.web.ts

@@ -0,0 +1,25 @@
+/** Apply DOM escape props after the primitive's own props. Dash-named keys
+ *  are attributes; other keys use the DOM property where available. */
+export function applyEscapeProps(element: any, props: { web?: any }): void {
+	if (!element || !props.web) {
+		return
+	}
+
+	for (const [key, value] of Object.entries(props.web)) {
+		if (key.includes('-')) {
+			if (value == null || value === false) {
+				element.removeAttribute(key)
+			} else {
+				element.setAttribute(key, value === true ? '' : String(value))
+			}
+		} else if (key in element) {
+			try {
+				element[key] = value
+			} catch {
+				element.setAttribute(key, String(value))
+			}
+		} else if (value != null) {
+			element.setAttribute(key, String(value))
+		}
+	}
+}

package/src/index.macos.ts

@@ -0,0 +1,2 @@
+export { Lottie } from './Lottie.macos.tsrx'
+export type { LottieEvent, LottieFit, LottieHandle, LottieProps } from './props'

package/src/index.ts

@@ -0,0 +1,2 @@
+export { Lottie } from './Lottie.tsrx'
+export type { LottieEvent, LottieFit, LottieHandle, LottieProps } from './props'

package/src/index.web.ts

@@ -0,0 +1,2 @@
+export { Lottie } from './Lottie.web.tsrx'
+export type { LottieEvent, LottieFit, LottieHandle, LottieProps } from './props'

package/src/layout-child.ts

@@ -0,0 +1,57 @@
+import type { LayoutChildProps, FlexContainerProps } from './props'
+
+// start/end shorthand → flex-start/flex-end.
+const FLEX_JUSTIFY: Record<string, string> = { start: 'flex-start', end: 'flex-end' }
+const FLEX_ALIGN: Record<string, string> = { start: 'flex-start', end: 'flex-end' }
+
+/** NativeScript reads these attributes from each child view during parent
+ *  layout. Values are forwarded with NativeScript's own property names.
+ *  The flex-container props (justifyContent/alignItems/flexWrap/gap) land on
+ *  the host flexboxlayout itself — its own attributes, not child metadata. */
+export function layoutChildProps(props: LayoutChildProps & Partial<FlexContainerProps>) {
+	const result: Record<string, any> = {}
+	for (const key of [
+		'row',
+		'col',
+		'rowSpan',
+		'colSpan',
+		'dock',
+		'left',
+		'top',
+		'flexGrow',
+		'flexShrink',
+		'alignSelf',
+		'order',
+	] as const) {
+		if (props[key] !== undefined) {
+			result[key] = props[key]
+		}
+	}
+
+	if (props.justifyContent !== undefined) {
+		result.justifyContent = FLEX_JUSTIFY[props.justifyContent] ?? props.justifyContent
+	}
+
+	if (props.alignItems !== undefined) {
+		result.alignItems = FLEX_ALIGN[props.alignItems] ?? props.alignItems
+	}
+
+	if (props.flexWrap !== undefined) {
+		result.flexWrap =
+			props.flexWrap === true ? 'wrap' : props.flexWrap === false ? 'nowrap' : props.flexWrap
+	}
+
+	if (props.gap !== undefined) {
+		result.gap = props.gap
+	}
+
+	if (props.rowGap !== undefined) {
+		result.rowGap = props.rowGap
+	}
+
+	if (props.columnGap !== undefined) {
+		result.columnGap = props.columnGap
+	}
+
+	return result
+}

package/src/layout-child.web.ts

@@ -0,0 +1,108 @@
+import type { LayoutChildProps, FlexContainerProps } from './props'
+
+/** The shared contract is "numbers are dips" (RN semantics), but octane's DOM
+ *  renderer keeps React's unitless list — lineHeight is unitless there, so
+ *  `style={{lineHeight: 40}}` would render a 40× multiplier instead of 40px.
+ *  lineHeight is the one unitless-in-React prop that is a length in the
+ *  shared vocabulary; force the px suffix. */
+export function normStyle(style: any) {
+	if (style && typeof style.lineHeight === 'number') {
+		return { ...style, lineHeight: style.lineHeight + 'px' }
+	}
+
+	return style
+}
+
+// start/end shorthand → flex-start/flex-end (valid in both engines).
+const FLEX_JUSTIFY: Record<string, string> = {
+	start: 'flex-start',
+	end: 'flex-end',
+}
+
+const FLEX_ALIGN: Record<string, string> = {
+	start: 'flex-start',
+	end: 'flex-end',
+}
+
+/** Convert parent-layout metadata to CSS on the web leaf. Native's `dock`
+ *  attribute has no CSS equivalent and is ignored on web. Grid indices are
+ *  zero-based in the shared API, matching NativeScript. */
+export function layoutChildProps(
+	props: LayoutChildProps & Partial<FlexContainerProps> & { style?: any },
+	baseStyle = props.style,
+) {
+	const style = { ...normStyle(baseStyle) }
+	if (props.row !== undefined) {
+		style.gridRow = `${props.row + 1} / span ${props.rowSpan ?? 1}`
+	} else if (props.rowSpan !== undefined) {
+		style.gridRow = `span ${props.rowSpan}`
+	}
+
+	if (props.col !== undefined) {
+		style.gridColumn = `${props.col + 1} / span ${props.colSpan ?? 1}`
+	} else if (props.colSpan !== undefined) {
+		style.gridColumn = `span ${props.colSpan}`
+	}
+
+	if (props.left !== undefined) {
+		style.left = props.left
+	}
+
+	if (props.top !== undefined) {
+		style.top = props.top
+	}
+
+	if (props.flexGrow !== undefined) {
+		style.flexGrow = props.flexGrow
+	}
+
+	if (props.flexShrink !== undefined) {
+		style.flexShrink = props.flexShrink
+	}
+
+	if (props.alignSelf !== undefined) {
+		style.alignSelf = props.alignSelf
+	}
+
+	if (props.order !== undefined) {
+		style.order = props.order
+	}
+
+	// Flex-container props (View/Row/Pressable hosts) — RN vocabulary on the
+	// element style. Numbers become px via octane's style normalization.
+	if (props.justifyContent !== undefined) {
+		style.justifyContent = FLEX_JUSTIFY[props.justifyContent] ?? props.justifyContent
+	}
+
+	if (props.alignItems !== undefined) {
+		style.alignItems = FLEX_ALIGN[props.alignItems] ?? props.alignItems
+	}
+
+	if (props.flexWrap !== undefined) {
+		style.flexWrap =
+			props.flexWrap === true ? 'wrap' : props.flexWrap === false ? 'nowrap' : props.flexWrap
+	}
+
+	if (props.gap !== undefined) {
+		style.gap = props.gap
+	}
+
+	if (props.rowGap !== undefined) {
+		style.rowGap = props.rowGap
+	}
+
+	if (props.columnGap !== undefined) {
+		style.columnGap = props.columnGap
+	}
+
+	// The shared contract is "numbers are dips" (RN semantics), but octane's
+	// DOM renderer keeps React's unitless list — lineHeight is unitless there,
+	// so `style={{lineHeight: 40}}` would render a 40× multiplier instead of
+	// 40px. lineHeight is the one unitless-in-React prop that is a length in
+	// the shared vocabulary; force the px suffix.
+	if (typeof style.lineHeight === 'number') {
+		style.lineHeight = style.lineHeight + 'px'
+	}
+
+	return { style }
+}

package/src/native-elements.d.ts

@@ -0,0 +1,8 @@
+import { LottieView } from './vendor/ui-lottie/src/lottie'
+import type { Attributes } from '@nativescript-community/octane/intrinsics'
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		xplatlottie: Attributes<typeof LottieView>
+	}
+}