Skip to content

πŸŽ₯ Make videos programmatically with React

12.9 KB
Raw Blame
import React, {
	createContext,
	forwardRef,
	useContext,
	useLayoutEffect,
	useMemo,
	useState,
} from 'react';
import {CanUseRemotionHooks} from './CanUseRemotionHooks.js';
import type {
	JsxComponentIdentity,
	SequenceControls,
} from './CompositionManager.js';
import {deleteNestedKey} from './delete-nested-key.js';
import {getPropStatusesForSequenceStatus} from './effects/use-memoized-effects.js';
import {
	getStackForControls,
	setStackForControls,
} from './enable-sequence-stack-traces.js';
import {
	flattenActiveSchema,
	getFlatSchemaWithAllKeys,
} from './flatten-schema.js';
import {
	extendSchemaWithSequenceName,
	type InteractivitySchema,
} from './interactivity-schema.js';
import {
	OptimisticSequenceDeletion,
	usePendingSequenceDeletions,
} from './optimistic-sequence-deletion.js';
import {createRuntimeValueStore} from './runtime-value-store.js';
import {OverrideIdsToNodePathsGettersContext} from './sequence-node-path.js';
import {
	useDragOverridesForNodePath,
	usePropStatusForNodePath,
} from './SequenceManager.js';
import {useCurrentFrameWithOptionalSubscription} from './use-current-frame.js';
import {useRemotionEnvironment} from './use-remotion-environment.js';
import {computeEffectiveSchemaValuesDotNotation} from './use-schema.js';
import {useUnsafeVideoConfig} from './use-unsafe-video-config.js';

export const getNestedValue = (
	obj: Record<string, unknown>,
	key: string,
): unknown => {
	const parts = key.split('.');
	let current: unknown = obj;
	for (const part of parts) {
		if (
			current === null ||
			current === undefined ||
			typeof current !== 'object'
		)
			return undefined;
		current = (current as Record<string, unknown>)[part];
	}

	return current;
};

export const getRuntimeValueForSchemaKey = ({
	flatSchema,
	key,
	props,
}: {
	flatSchema: InteractivitySchema;
	key: string;
	props: Record<string, unknown>;
}): unknown => {
	const value = getNestedValue(props, key);

	if (
		(flatSchema[key]?.type === 'string' ||
			flatSchema[key]?.type === 'text-content') &&
		typeof value !== 'string'
	) {
		return undefined;
	}

	return value;
};

export const readValuesFromProps = (
	props: Record<string, unknown>,
	keys: string[],
	flatSchema?: InteractivitySchema,
): Record<string, unknown> => {
	const out: Record<string, unknown> = {};
	for (const key of keys) {
		out[key] = flatSchema
			? getRuntimeValueForSchemaKey({flatSchema, key, props})
			: getNestedValue(props, key);
	}

	return out;
};

export const selectActiveKeys = (
	schema: InteractivitySchema,
	values: Record<string, unknown>,
): string[] => {
	return Object.keys(flattenActiveSchema(schema, (key) => values[key]));
};

export const mergeValues = ({
	flatSchema,
	props,
	valuesDotNotation,
	schemaKeys,
	propsToDelete,
}: {
	flatSchema: InteractivitySchema;
	props: Record<string, unknown>;
	valuesDotNotation: Record<string, unknown>;
	schemaKeys: string[];
	propsToDelete: Set<string>;
}): Record<string, unknown> => {
	const merged = {...props};

	for (const key of schemaKeys) {
		const value = valuesDotNotation[key];
		if (
			(flatSchema[key]?.type === 'string' ||
				flatSchema[key]?.type === 'text-content') &&
			value === undefined
		) {
			continue;
		}

		const parts = key.split('.');

		if (parts.length === 1) {
			merged[key] = value;

			continue;
		}

		// For dot-notation keys like 'style.opacity',
		// clone and set the nested path
		let current = merged;
		for (let i = 0; i < parts.length - 1; i++) {
			const part = parts[i];
			if (typeof current[part] === 'object' && current[part] !== null) {
				current[part] = {...(current[part] as Record<string, unknown>)};
			} else {
				current[part] = {};
			}

			current = current[part] as Record<string, unknown>;
		}

		current[parts[parts.length - 1]] = value;
	}

	const propsToDeleteWithoutTextContent = new Set(
		[...propsToDelete].filter(
			(key) =>
				!(
					(flatSchema[key]?.type === 'string' ||
						flatSchema[key]?.type === 'text-content') &&
					valuesDotNotation[key] === undefined
				),
		),
	);
	deleteNestedKey(merged, propsToDeleteWithoutTextContent);

	return merged;
};

export type WithInteractivitySchemaOptions<
	S extends InteractivitySchema,
	Props extends object,
> = {
	Component: React.ComponentType<
		Props & {readonly controls: SequenceControls | undefined}
	>;
	componentName: string;
	/** @internal */
	componentIdentity?: JsxComponentIdentity | null;
	schema: S;
	supportsEffects: boolean;
};

const DisableInteractivityContext = createContext(false);

export const DisableInteractivityProvider: React.FC<{
	readonly children: React.ReactNode;
}> = ({children}) => {
	return React.createElement(
		DisableInteractivityContext.Provider,
		{value: true},
		children,
	);
};

// Authoring surfaces outside the Studio, such as @remotion/sdk, opt into
// populating `controls` and applying Visual Mode overrides.
const EnableInteractivityContext = createContext(false);

export const EnableInteractivityProvider: React.FC<{
	readonly children: React.ReactNode;
}> = ({children}) => {
	return React.createElement(
		EnableInteractivityContext.Provider,
		{value: true},
		children,
	);
};

export const withInteractivitySchema = <
	S extends InteractivitySchema,
	Props extends object,
>({
	Component,
	componentName,
	componentIdentity = null,
	schema,
	supportsEffects,
}: WithInteractivitySchemaOptions<S, Props>): React.ComponentType<Props> => {
	// Schema is static for a component, so we move this outside
	const schemaWithSequenceName = extendSchemaWithSequenceName(schema);
	const flatSchema = getFlatSchemaWithAllKeys(schemaWithSequenceName);
	const flatKeys = Object.keys(flatSchema);
	// A structural edit can put a different component at the same stack.
	// Only reuse overrides for instances of this component.
	const stackToOverrideMap: Record<string, string> = {};

	const Wrapped = forwardRef<unknown, Props>((props, ref) => {
		const {
			_remotionInternalStack: internalStack,
			...propsWithoutInternalStack
		} = props as Props & {readonly _remotionInternalStack?: string};
		const cleanProps = propsWithoutInternalStack as Props;
		const env = useRemotionEnvironment();
		const pendingDeletions = usePendingSequenceDeletions();
		const canUseRemotionHooks = useContext(CanUseRemotionHooks);
		const disableInteractivity = useContext(DisableInteractivityContext);
		const enableInteractivity = useContext(EnableInteractivityContext);

		if (
			(!env.isStudio && !enableInteractivity) ||
			env.isRendering ||
			!canUseRemotionHooks ||
			disableInteractivity
		) {
			return React.createElement(Component, {
				...cleanProps,
				controls: null,
				ref,
			} as Props & {
				controls: SequenceControls | undefined;
				ref: typeof ref;
			});
		}

		// eslint-disable-next-line react-hooks/rules-of-hooks
		const nodePathMapping = useContext(OverrideIdsToNodePathsGettersContext);
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const videoConfig = useUnsafeVideoConfig();
		const durationInFrames = videoConfig?.durationInFrames;
		const fps = videoConfig?.fps;
		const height = videoConfig?.height;
		const width = videoConfig?.width;
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const videoConfigValues = useMemo(
			() =>
				durationInFrames === undefined ||
				fps === undefined ||
				height === undefined ||
				width === undefined
					? null
					: {
							durationInFrames,
							fps,
							height,
							width,
						},
			[durationInFrames, fps, height, width],
		);

		// Keep parent controls intact when adding missing source information.
		// @ts-expect-error
		const passedControls = cleanProps.controls as
			| SequenceControls
			| null
			| undefined;
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const resolvedPassedControls = useMemo(() => {
			if (
				!passedControls ||
				getStackForControls(passedControls) !== null ||
				internalStack === undefined
			) {
				return passedControls;
			}

			const controlsWithStack = {...passedControls};
			setStackForControls(controlsWithStack, internalStack);
			return controlsWithStack;
		}, [internalStack, passedControls]);
		if (resolvedPassedControls) {
			return React.createElement(Component, {
				...cleanProps,
				controls: resolvedPassedControls,
				ref,
			} as unknown as Props & {
				controls: SequenceControls | undefined;
				ref: typeof ref;
			});
		}

		// eslint-disable-next-line react-hooks/rules-of-hooks
		const [overrideId] = useState(() => {
			if (!internalStack) {
				return String(Math.random());
			}

			const existingOverrideId = stackToOverrideMap[internalStack];
			if (existingOverrideId) {
				return existingOverrideId;
			}

			const newOverrideId = String(Math.random());
			stackToOverrideMap[internalStack] = newOverrideId;
			return newOverrideId;
		});
		const nodePath = env.isReadOnlyStudio
			? null
			: (nodePathMapping.overrideIdToNodePathMappings[overrideId] ?? null);
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const dragOverrides = useDragOverridesForNodePath(nodePath);
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const sequenceStatus = usePropStatusForNodePath(nodePath);
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const propStatus = useMemo(
			() => getPropStatusesForSequenceStatus(sequenceStatus, videoConfigValues),
			[sequenceStatus, videoConfigValues],
		);
		// Runtime props already update through their owner. Only overrides with
		// keyframes need this wrapper to subscribe to the advancing clock.
		const needsFrame = flatKeys.some(
			(key) =>
				propStatus?.[key]?.status === 'keyframed' ||
				dragOverrides[key]?.type === 'keyframed',
		);
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const frame = useCurrentFrameWithOptionalSubscription(needsFrame);

		// Read the runtime values for every flat key from the JSX props,
		// memoized on the leaf values so the object reference is stable
		// when nothing changed β€” otherwise downstream `useMemo`s churn and
		// effects (e.g. Sequence registration) re-fire every render.
		const runtimeValues = flatKeys.map((key) =>
			getRuntimeValueForSchemaKey({
				flatSchema,
				key,
				props: cleanProps as Record<string, unknown>,
			}),
		);
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const currentRuntimeValueDotNotation = useMemo(
			() =>
				readValuesFromProps(
					cleanProps as Record<string, unknown>,
					flatKeys,
					flatSchema,
				),
			// eslint-disable-next-line react-hooks/exhaustive-deps
			runtimeValues,
		);
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const [runtimeValueStore] = useState(() =>
			createRuntimeValueStore(currentRuntimeValueDotNotation),
		);
		// Publishing in a layout effect ensures that abandoned renders cannot expose
		// uncommitted runtime values to Studio consumers.
		// eslint-disable-next-line react-hooks/rules-of-hooks
		useLayoutEffect(() => {
			runtimeValueStore.setSnapshot(currentRuntimeValueDotNotation);
		}, [currentRuntimeValueDotNotation, runtimeValueStore]);

		// eslint-disable-next-line react-hooks/rules-of-hooks
		const controls = useMemo((): SequenceControls => {
			const controlsForRender = {
				schema: schemaWithSequenceName,
				currentRuntimeValueDotNotation,
				runtimeValues: runtimeValueStore.store,
				videoConfigValues,
				overrideId,
				supportsEffects,
				componentIdentity,
				componentName,
			};
			setStackForControls(controlsForRender, internalStack);
			return controlsForRender;
		}, [
			currentRuntimeValueDotNotation,
			internalStack,
			overrideId,
			runtimeValueStore.store,
			videoConfigValues,
		]);

		// Keep source identities available to parents that inspect their children
		// before rendering them (Series and TransitionSeries).
		// eslint-disable-next-line react-hooks/rules-of-hooks
		useLayoutEffect(() => {
			OptimisticSequenceDeletion.register(internalStack ?? null, nodePath);
		}, [internalStack, nodePath]);

		// 3. Apply drag/code overrides on top of the runtime values.
		// eslint-disable-next-line react-hooks/rules-of-hooks
		const {merged: valuesDotNotation, propsToDelete} = useMemo(() => {
			return computeEffectiveSchemaValuesDotNotation({
				schema: schemaWithSequenceName,
				currentValue: currentRuntimeValueDotNotation,
				overrideValues: dragOverrides,
				propStatus,
				frame,
			});
		}, [currentRuntimeValueDotNotation, dragOverrides, propStatus, frame]);

		// 4. Eliminate values forbidden by the resolved discriminated union.
		const activeKeys = selectActiveKeys(
			schemaWithSequenceName,
			valuesDotNotation,
		);

		// 5. Apply the active values back onto the props.
		const mergedProps = mergeValues({
			flatSchema,
			props: cleanProps as Record<string, unknown>,
			valuesDotNotation,
			schemaKeys: activeKeys,
			propsToDelete,
		});

		if (OptimisticSequenceDeletion.isDeleted(nodePath, pendingDeletions)) {
			return null;
		}

		return React.createElement(Component, {
			...mergedProps,
			controls,
			ref,
		} as Props & {
			controls: SequenceControls | undefined;
			ref: typeof ref;
		});
	});

	Wrapped.displayName = `withInteractivitySchema(${Component.displayName || Component.name || 'Component'})`;

	return Wrapped as unknown as React.ComponentType<Props>;
};