@cesdk/engine 1.62.0-rc.1 → 1.63.0-nightly.20251014

package/index.d.ts

@@ -5517,6 +5517,32 @@ export declare type Color = RGBAColor | CMYKColor | SpotColor;
  */
 export declare type ColorSpace = 'sRGB' | 'CMYK' | 'SpotColor';
 
+/**
+ * Combines multiple reactive properties into a single reactive property.
+ *
+ * Similar to `combineLatest` from RxJS but simpler. Emits whenever any source emits.
+ *
+ * @example
+ * ```typescript
+ * const x = createReactiveProperty(0);
+ * const y = createReactiveProperty(0);
+ *
+ * const position = combineProperties([x, y]);
+ *
+ * position.subscribe(([xVal, yVal]) => {
+ *   console.log(`Position: (${xVal}, ${yVal})`);
+ * });
+ * ```
+ *
+ * @param properties - Array of reactive properties to combine
+ * @param options - Configuration options
+ * @returns A reactive property containing an array of values
+ * @public
+ */
+export declare function _combineProperties<T extends any[]>(properties: {
+    [K in keyof T]: _ReadonlyReactiveProperty<T[K]>;
+}, options?: Pick<_ReactivePropertyOptions<T>, 'equals'>): _ReadonlyReactiveProperty<T>;
+
 /**
  * Asset results that are returned from the engine.
  *
@@ -5600,6 +5626,69 @@ export declare interface Configuration {
  */
 export declare type ContentFillMode = 'Crop' | 'Cover' | 'Contain';
 
+/**
+ * Creates a derived reactive property from one or more sources.
+ *
+ * The value is computed from source values using a derivation function.
+ * Updates are memoized (only emit when derived value changes).
+ *
+ * @example
+ * ```typescript
+ * const width = createReactiveProperty(800);
+ * const height = createReactiveProperty(600);
+ *
+ * const area = createDerivedProperty(
+ *   [width, height],
+ *   (w, h) => w * h
+ * );
+ *
+ * area.subscribe((value) => console.log('Area:', value));
+ * width.update(1000); // Logs: "Area: 600000"
+ * ```
+ *
+ * @param sources - Array of reactive properties or sources to track
+ * @param derive - Function that computes the derived value from source values
+ * @param options - Configuration options
+ * @returns A read-only reactive property
+ * @public
+ */
+export declare function _createDerivedProperty<T, S extends any[]>(sources: {
+    [K in keyof S]: _ReadonlyReactiveProperty<S[K]> | _Source<S[K]>;
+}, derive: (...values: S) => T, options?: Pick<_ReactivePropertyOptions<T>, 'equals'>): _ReadonlyReactiveProperty<T>;
+
+/**
+ * Creates a reactive property with subscribe, value, and update methods.
+ *
+ * This is the main utility for managing state with change notifications.
+ * Values are memoized by default (only emit when value changes).
+ *
+ * @example
+ * ```typescript
+ * // Simple value
+ * const zoom = createReactiveProperty(1.0);
+ * zoom.subscribe((value) => console.log('Zoom:', value));
+ * zoom.update(2.0); // Logs: "Zoom: 2.0"
+ *
+ * // With custom equality for objects
+ * const settings = createReactiveProperty(
+ *   { width: 800, height: 600 },
+ *   { equals: isEqual }
+ * );
+ *
+ * // With initial value emission
+ * const formats = createReactiveProperty(
+ *   defaultFormats,
+ *   { emitOnSubscribe: true }
+ * );
+ * ```
+ *
+ * @param initialValue - The initial value of the property
+ * @param options - Configuration options
+ * @returns A reactive property with subscribe, value, and update methods
+ * @public
+ */
+export declare function _createReactiveProperty<T>(initialValue: T, options?: _ReactivePropertyOptions<T>): _ReactiveProperty<T>;
+
 /**
  * Options for creating a video scene.
  * @public
@@ -5617,6 +5706,44 @@ export declare type CreateSceneOptions = {
     };
 };
 
+/**
+ * Creates a reactive property that tracks a source and updates based on a getter/setter.
+ *
+ * This is useful for wrapping engine properties or complex state logic.
+ *
+ * @example
+ * ```typescript
+ * const settings = createTrackedProperty(
+ *   // Getter
+ *   () => {
+ *     const camera = engine.block.findByType('camera')[0];
+ *     return {
+ *       width: engine.block.getFloat(camera, 'camera/resolution/width'),
+ *       height: engine.block.getFloat(camera, 'camera/resolution/height')
+ *     };
+ *   },
+ *   // Setter
+ *   ({ width, height }) => {
+ *     const camera = engine.block.findByType('camera')[0];
+ *     engine.block.setFloat(camera, 'camera/resolution/width', width);
+ *     engine.block.setFloat(camera, 'camera/resolution/height', height);
+ *   },
+ *   // Source to track
+ *   onCameraUpdated,
+ *   // Options
+ *   { equals: isEqual }
+ * );
+ * ```
+ *
+ * @param getter - Function to get current value
+ * @param setter - Function to update value
+ * @param source - Source to track for updates
+ * @param options - Configuration options
+ * @returns A reactive property
+ * @public
+ */
+export declare function _createTrackedProperty<T, U = any>(getter: () => T, setter: (value: T) => void, source: (listener: _Listener<U>) => _Unsubscribe, options?: Pick<_ReactivePropertyOptions<T>, 'equals'>): _ReactiveProperty<T>;
+
 /**
  * The CreativeEngine is the core processing unit of CE.SDK and handles state management, rendering, input handling, and much more.
  * It provides APIs to directly interact with assets, blocks, scenes, and variables. These APIs can be used in a headless environment
@@ -6831,6 +6958,12 @@ export declare type EnginePluginContext = {
     engine: CreativeEngine;
 };
 
+/**
+ * A function that compares two values for equality
+ * @public
+ */
+export declare type _EqualsFn<T> = (a: T, b: T | undefined) => boolean;
+
 /**
  * @public Subscribe to block lifecycle events in the design engine.
  *
@@ -7192,6 +7325,28 @@ export declare function isRGBAColor(color: Color): color is RGBAColor;
  */
 export declare function isSpotColor(color: Color): color is SpotColor;
 
+/**
+ * A simplified source type for legacy API streams
+ * @public
+ */
+export declare type _LegacySource<T> = (handler: (value: T) => void) => () => void;
+
+/**
+ * Lightweight reactive state utilities for managing subscriptions and state updates.
+ *
+ * This module provides a set of composable utilities for creating reactive properties
+ * without the overhead of a full reactive framework. It's designed to replace the
+ * previous Channel abstraction with simpler, more focused primitives.
+ *
+ * @module reactiveState
+ * @public
+ */
+/**
+ * A listener function that receives value updates
+ * @public
+ */
+export declare type _Listener<T> = (value: T) => void;
+
 /**
  * e.g. `en`, `de`, etc.
  * @public
@@ -7247,6 +7402,58 @@ export declare const LogLevel: {
     readonly Error: "Error";
 };
 
+/**
+ * Creates a simple event source that can emit values to subscribed listeners.
+ *
+ * This is the most basic building block - a pub/sub pattern without state management.
+ *
+ * @example
+ * ```typescript
+ * const onResize = makeSource<{ width: number; height: number }>();
+ *
+ * // Subscribe
+ * const unsubscribe = onResize((size) => {
+ *   console.log('New size:', size);
+ * });
+ *
+ * // Emit
+ * onResize.emit({ width: 800, height: 600 });
+ *
+ * // Cleanup
+ * unsubscribe();
+ * ```
+ *
+ * @returns A source function with an emit method
+ * @public
+ */
+export declare function _makeSource<T>(): _Source<T>;
+
+/**
+ * Merges multiple event sources into a single source that emits when any source emits.
+ *
+ * This is useful for tracking properties that depend on multiple independent events.
+ *
+ * @example
+ * ```typescript
+ * const zoomChanged = engine.scene.onZoomLevelChanged;
+ * const dpiChanged = engine.scene.onDpiChanged;
+ *
+ * const zoomOrDpiChanged = mergeSources(zoomChanged, dpiChanged);
+ *
+ * // Now use with createTrackedProperty
+ * const normalizedZoom = createTrackedProperty(
+ *   () => engine.scene.getZoomLevel() / getDpi(),
+ *   (value) => engine.scene.setZoomLevel(value * getDpi()),
+ *   zoomOrDpiChanged
+ * );
+ * ```
+ *
+ * @param sources - Event source functions to merge
+ * @returns A merged source that emits when any source emits
+ * @public
+ */
+export declare function _mergeSources(...sources: Array<(listener: _Listener<any>) => _Unsubscribe>): (listener: _Listener<void>) => _Unsubscribe;
+
 /**
  * Represents the MIME types used in the editor.
  *
@@ -7429,6 +7636,46 @@ export declare interface Reaction {
     dispose(): void;
 }
 
+/**
+ * A reactive property with subscribe, value, and update methods
+ * @public
+ */
+export declare interface _ReactiveProperty<T> {
+    /**
+     * Subscribe to value changes
+     * @param listener - Function to call when value changes
+     * @returns Unsubscribe function
+     */
+    subscribe: (listener: _Listener<T>) => _Unsubscribe;
+    /**
+     * Get current value
+     */
+    value: () => T;
+    /**
+     * Update the value (will notify listeners if changed)
+     */
+    update: (newValue: T) => void;
+}
+
+/**
+ * Options for creating a reactive property
+ * @public
+ */
+export declare interface _ReactivePropertyOptions<T> {
+    /**
+     * Equality comparison function (default: strict equality)
+     */
+    equals?: _EqualsFn<T>;
+    /**
+     * If true, emit the initial value to new subscribers
+     */
+    emitOnSubscribe?: boolean;
+    /**
+     * Optional source to track (will subscribe and forward updates)
+     */
+    trackSource?: (listener: _Listener<any>) => _Unsubscribe;
+}
+
 /**
  * The reactor coordinates the update of registered _Reactions_.
  *
@@ -7468,6 +7715,23 @@ export declare interface Reactor {
     nextReaction: Promise<void>;
 }
 
+/**
+ * A read-only reactive property with subscribe and value methods
+ * @public
+ */
+export declare interface _ReadonlyReactiveProperty<T> {
+    /**
+     * Subscribe to value changes
+     * @param listener - Function to call when value changes
+     * @returns Unsubscribe function
+     */
+    subscribe: (listener: _Listener<T>) => _Unsubscribe;
+    /**
+     * Get current value
+     */
+    value: () => T;
+}
+
 /**
  * Dispatched on the engine canvas right before the engine will refocus its text
  * input after a blur. Call `preventDefault()` to prevent the refocusing.
@@ -8453,6 +8717,15 @@ export declare interface Source {
     height: number;
 }
 
+/**
+ * A source that can emit values to subscribed listeners
+ * @public
+ */
+export declare interface _Source<T> {
+    (listener: _Listener<T>): _Unsubscribe;
+    emit: (value: T) => void;
+}
+
 /**
  * Options for configuring block split operations.
  * @public
@@ -8731,6 +9004,12 @@ export declare interface _UBQSplitOptions {
     selectNewBlock: boolean;
 }
 
+/**
+ * An unsubscribe function that removes a listener
+ * @public
+ */
+export declare type _Unsubscribe = () => void;
+
 /**
  * @public Manage text variables within design templates.
  *