@octane-xplat/lottie 0.9.0 → 0.11.0

package/src/Lottie.web.tsrx

@@ -1,5 +1,5 @@
 import lottie, { type AnimationItem } from 'lottie-web';
-import { useEffect, useRef } from 'octane';
+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';
@@ -18,6 +18,7 @@ const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
  *  (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);
@@ -27,23 +28,38 @@ export function Lottie(props: LottieProps) @{
 	const build = (host: HTMLDivElement) => {
 		anim.current?.destroy();
 		anim.current = null;
+		setAnimation(null);
 		ready.current = false;
 
-		const animationData = props.data ?? (props.src?.startsWith('{') ? JSON.parse(props.src) : undefined);
+		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;
 
-		const 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'] },
+		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;
@@ -112,12 +128,13 @@ export function Lottie(props: LottieProps) @{
 		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);
-			if (anim.current) props.bind?.(handle(anim.current));
 		}}
 		id={props.id}
 		className={props.className}

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/props.ts

@@ -1,3 +1,5 @@
+import type { Octane } from 'octane/jsx-runtime'
+
 export interface LayoutChildProps {
 	row?: number
 	col?: number
@@ -85,6 +87,9 @@ export interface LottieHandle {
 /** Lottie animation — lottie-web (svg renderer) on web, vendored
  *  ui-lottie (`src/vendor/ui-lottie` submodule, `octane-xplat/ui-lottie`
  *  @ `xplat-vendored`) on native.
+ *  On web, lottie-web evaluates expressions embedded in animation data as
+ *  JavaScript. Load only trusted animation data; expression-bearing files
+ *  require a CSP that allows `unsafe-eval`.
  *  Progress is always normalized 0..1 and durations are milliseconds on
  *  every platform (the native plugin reports seconds on iOS). */
 export interface LottieProps extends LayoutChildProps, AccessibilityProps {
@@ -120,7 +125,7 @@ export interface LottieProps extends LayoutChildProps, AccessibilityProps {
 	onError?: (e: LottieEvent) => void
 	/** Imperative handle — play/pause/seek plus `native` for anything the
 	 *  shared props don't cover. */
-	bind?: (h: LottieHandle) => void
+	ref?: Octane.Ref<LottieHandle>
 	/** Platform escape hatches, applied after the shared props. */
 	ios?: Record<string, any>
 	android?: Record<string, any>

package/types/generated/props.d.ts

@@ -1,3 +1,4 @@
+import type { Octane } from 'octane/jsx-runtime';
 export interface LayoutChildProps {
     row?: number;
     col?: number;
@@ -63,6 +64,9 @@ export interface LottieHandle {
 /** Lottie animation — lottie-web (svg renderer) on web, vendored
  *  ui-lottie (`src/vendor/ui-lottie` submodule, `octane-xplat/ui-lottie`
  *  @ `xplat-vendored`) on native.
+ *  On web, lottie-web evaluates expressions embedded in animation data as
+ *  JavaScript. Load only trusted animation data; expression-bearing files
+ *  require a CSP that allows `unsafe-eval`.
  *  Progress is always normalized 0..1 and durations are milliseconds on
  *  every platform (the native plugin reports seconds on iOS). */
 export interface LottieProps extends LayoutChildProps, AccessibilityProps {
@@ -98,7 +102,7 @@ export interface LottieProps extends LayoutChildProps, AccessibilityProps {
     onError?: (e: LottieEvent) => void;
     /** Imperative handle — play/pause/seek plus `native` for anything the
      *  shared props don't cover. */
-    bind?: (h: LottieHandle) => void;
+    ref?: Octane.Ref<LottieHandle>;
     /** Platform escape hatches, applied after the shared props. */
     ios?: Record<string, any>;
     android?: Record<string, any>;