@cesdk/engine 1.31.0 → 1.32.0-rc.0

package/index.d.ts

@@ -42,6 +42,8 @@ export declare interface Asset {
 export declare class AssetAPI {
     #private;
 
+
+
     /**
      * Adds a custom asset source. Its ID has to be unique.
      * @param source - The asset source.
@@ -132,6 +134,7 @@ export declare class AssetAPI {
      * @param block - The block the asset should be applied to.
      */
     applyToBlock(sourceId: string, assetResult: AssetResult, block: DesignBlockId): Promise<void>;
+    unstable_applyProperty(sourceId: string, assetResult: AssetResult, property: AssetProperty): Promise<void>;
     /**
      * The default implementation for applying an asset to the scene.
      * This implementation is used when no `applyAsset` function is provided to `addSource`.
@@ -156,9 +159,31 @@ export declare class AssetAPI {
      * @returns A method to unsubscribe.
      */
     onAssetSourceRemoved: (callback: (sourceID: string) => void) => (() => void);
+    /**
+     * Register a callback to be called every time an asset source's contents are changed.
+     * @param callback - The function that is called whenever an asset source is updated.
+     * @returns A method to unsubscribe.
+     */
+    onAssetSourceUpdated: (callback: (sourceID: string) => void) => (() => void);
+    /**
+     * Notifies the engine that the contents of an asset source changed.
+     * @param sourceID - The asset source whose contents changed.
+     */
+    assetSourceContentsChanged(sourceID: string): void;
 
 }
 
+/**
+ * Asset boolean property definition
+ * @public
+ */
+export declare interface AssetBooleanProperty {
+    property: string;
+    type: 'Boolean';
+    value: boolean;
+    defaultValue: boolean;
+}
+
 /**
  * Asset Color payload CMYK representation
  * @public
@@ -177,6 +202,17 @@ export declare interface AssetCMYKColor {
  */
 export declare type AssetColor = AssetRGBColor | AssetCMYKColor | AssetSpotColor;
 
+/**
+ * Asset color property definition
+ * @public
+ */
+export declare interface AssetColorProperty {
+    property: string;
+    type: 'Color';
+    value: AssetColor;
+    defaultValue: AssetColor;
+}
+
 /**
  * Definition of an asset used if an asset is added to an asset source.
  * @public
@@ -196,6 +232,18 @@ export declare interface AssetDefinition extends Asset {
     tags?: Record<Locale, string[]>;
 }
 
+/**
+ * Asset enum property definition
+ * @public
+ */
+export declare interface AssetEnumProperty {
+    property: string;
+    type: 'Enum';
+    value: string;
+    defaultValue: string;
+    options: string[];
+}
+
 /**
  * An asset can be member of multiple groups. Groups have a semantic meaning
  * used to build and group UIs exploring the assets, e.g.sections in the
@@ -232,6 +280,20 @@ export declare type AssetMetaData = {
     blurType?: BlurType;
 } & Record<string, unknown>;
 
+/**
+ * Asset number property definition
+ * @public
+ */
+export declare interface AssetNumberProperty {
+    property: string;
+    type: 'Integer' | 'Float' | 'Double';
+    value: number;
+    defaultValue: number;
+    min: number;
+    max: number;
+    step: number;
+}
+
 /**
  * Asset payload
  * @public
@@ -240,8 +302,15 @@ export declare interface AssetPayload {
     color?: AssetColor;
     sourceSet?: Source[];
     typeface?: Typeface;
+    properties?: AssetProperty[];
 }
 
+/**
+ * Asset property for payload
+ * @public
+ */
+export declare type AssetProperty = AssetBooleanProperty | AssetColorProperty | AssetEnumProperty | AssetNumberProperty | AssetStringProperty;
+
 /**
  * Defines a request for querying assets
  * @public
@@ -280,6 +349,10 @@ export declare interface AssetQueryData {
      * If empty, the assets are sorted by the index.
      */
     sortKey?: string;
+    /**
+     * Sort assets that are marked as active first.
+     */
+    sortActiveFirst?: boolean;
 }
 
 /**
@@ -293,6 +366,8 @@ export declare interface AssetResult extends Asset {
     label?: string;
     /** The tags of this asset. Used for filtering and free-text searching. */
     tags?: string[];
+    /** If the asset is marked as active, i.e., used in a currently selected element. */
+    active?: boolean;
     /** Credits for the artist of the asset */
     credits?: {
         name: string;
@@ -422,6 +497,17 @@ export declare interface AssetsQueryResult<T extends AssetResult = AssetResult>
 
 declare type _AssetsQueryResult = AssetsQueryResult;
 
+/**
+ * Asset string property definition
+ * @public
+ */
+export declare interface AssetStringProperty {
+    property: string;
+    type: 'String';
+    value: string;
+    defaultValue: string;
+}
+
 /**
  * @public
  */
@@ -2768,7 +2854,7 @@ export declare type BlockState = BlockStateError | BlockStatePending | BlockStat
 /** @public There's an error preventing rendering. */
 export declare interface BlockStateError {
     type: 'Error';
-    error: 'AudioDecoding' | 'FileDecoding' | 'FileFetch' | 'Unknown' | 'VideoDecoding';
+    error: 'AudioDecoding' | 'ImageDecoding' | 'FileFetch' | 'Unknown' | 'VideoDecoding';
 }
 
 /** @public There is an ongoing operation on the block. Rendering may be affected. */
@@ -2918,6 +3004,8 @@ export declare interface CompleteAssetResult extends AssetResult {
     context: {
         sourceId: string;
     };
+    /** This is optional in `AssetResult` but always present here */
+    active: boolean;
 }
 
 /**
@@ -3240,22 +3328,9 @@ declare class CreativeEngine {
 
 
     /**
-     * Add a plugin to the engine. If a plugin URL is provided, the plugin will be
-     * loaded from that URL. Otherwise, the argument is expected to be a valid plugin
-     *
-     * A plugin can have the following methods:
-     * - `initialize` - Called once when the plugin is added to the engine
-     * - `update` - Called every frame
-     *
-     * PLEASE NOTE: Only Plugins provded via URL will be executed in the worker, e.g.
-     * during the video export the update method will be called.
-     *
-     * Please be aware that this is experimental right now. This API can change or
-     * be replaced or even removed completely in future versions.
+     * Adds and initializes a plugin to the engine.
      */
-    unstable_addPlugin(plugin: EnginePlugin & {
-        url?: string;
-    }): Promise<void>;
+    addPlugin(plugin: EnginePlugin): void;
     /**
      * Some browsers exhibit a bug where support for certain video codecs is
      * offered, but when attempting to decode or encode in these codecs, the
@@ -3268,6 +3343,7 @@ declare class CreativeEngine {
      */
     unstable_setVideoExportInactivityTimeout(timeout: number): void;
 
+
     /**
      * Install the mousewheel event handler for the CreativeEngine on a different
      * element than the canvas.
@@ -3341,7 +3417,6 @@ declare class CreativeEngine {
     }): Promise<void>;
 
 
-
 }
 export default CreativeEngine;
 
@@ -3411,6 +3486,9 @@ export declare type DesignBlockTypeShorthand = 'scene' | 'stack' | 'camera' | 'p
  */
 export declare type DesignUnit = 'Pixel' | 'Millimeter' | 'Inch';
 
+/** @public */
+export declare type EditMode = 'Transform' | 'Crop' | 'Text' | 'Playback' | 'Trim' | (string & {});
+
 /**
  * @public
  */
@@ -3432,15 +3510,15 @@ export declare class EditorAPI {
      * Set the edit mode of the editor.
      * An edit mode defines what type of content can currently be edited by the user.
      * Hint: the initial edit mode is "Transform".
-     * @param mode - "Transform", "Crop", "Text", "Playback", or a custom value.
+     * @param mode - "Transform", "Crop", "Text", "Playback", "Trim" or a custom value.
      */
-    setEditMode(mode: 'Transform' | 'Crop' | 'Text' | 'Playback' | string): void;
+    setEditMode(mode: EditMode): void;
     /**
      * Get the current edit mode of the editor.
      * An edit mode defines what type of content can currently be edited by the user.
-     * @returns "Transform", "Crop", "Text", "Playback", or a custom value.
+     * @returns "Transform", "Crop", "Text", "Playback", "Trim" or a custom value.
      */
-    getEditMode(): 'Transform' | 'Crop' | 'Text' | 'Playback' | string;
+    getEditMode(): EditMode;
     /**
      * Get the type of cursor that should be displayed by the application.
      * @returns The cursor type.
@@ -3845,6 +3923,14 @@ export declare class EditorAPI {
     getBufferLength(uri: string): number;
 
 
+    /**
+     * Returns the mimetype of the resources at the given URI.
+     * If the resource is not already downloaded, this function will download it.
+     * @param uri - The URI of the resource.
+     * @returns The mimetype of the resource.
+     * @throws An error if the resource could not be downloaded or the mimetype could not be determined.
+     */
+    getMimeType(uri: string): Promise<string>;
 }
 
 /**
@@ -3870,10 +3956,23 @@ export declare type EffectTypeShorthand = 'adjustments' | 'cross_cut' | 'dot_pat
 
 /** @public */
 export declare interface EnginePlugin {
-    initialize?: (context: PluginContext) => void;
-    update?: (context: PluginContext) => void;
+    name: string;
+    version: string;
+    initialize: (context: EnginePluginContext) => void;
 }
 
+/** @public */
+export declare type EnginePluginContext = {
+    engine: {
+        asset: AssetAPI;
+        block: BlockAPI;
+        scene: SceneAPI;
+        editor: EditorAPI;
+        event: EventAPI;
+        variable: VariableAPI;
+    };
+};
+
 /**
  * @public
  */
@@ -4013,6 +4112,7 @@ declare interface FindAssetsQuery {
     locale: string;
     sortingOrder: SortingOrder;
     sortKey: string;
+    sortActiveFirst: boolean;
 }
 
 /** @public */
@@ -4117,6 +4217,24 @@ export declare interface HTMLCreativeEngineCanvasElement extends HTMLElement {
     clear(): void;
 }
 
+/**
+ * Type guard for {@link CMYKColor}
+ * @public
+ */
+export declare function isCMYKColor(color: Color): color is CMYKColor;
+
+/**
+ * Type guard for {@link RGBAColor}
+ * @public
+ */
+export declare function isRGBAColor(color: Color): color is RGBAColor;
+
+/**
+ * Type guard for {@link SpotColor}
+ * @public
+ */
+export declare function isSpotColor(color: Color): color is SpotColor;
+
 /**
  * e.g. `en`, `de`, etc.
  * @public
@@ -4203,15 +4321,6 @@ export declare interface PageDuration {
  */
 export declare type PaletteColor = HexColorString | RGBColor | RGBAColor | SpotColor;
 
-declare type PluginContext = {
-    asset: AssetAPI;
-    block: BlockAPI;
-    scene: SceneAPI;
-    editor: EditorAPI;
-    event: EventAPI;
-    variable: VariableAPI;
-};
-
 /**
  * - Absolute: Position in absolute design units.
  * - Percent: Position in relation to the block's parent's size in percent, where 1.0 means 100%.
@@ -4605,7 +4714,7 @@ export declare type SceneMode = 'Design' | 'Video';
 /**
  * @public
  */
-export declare type Scope = 'text/edit' | 'text/character' | 'fill/change' | 'fill/changeType' | 'stroke/change' | 'shape/change' | 'layer/move' | 'layer/resize' | 'layer/rotate' | 'layer/flip' | 'layer/crop' | 'layer/opacity' | 'layer/blendMode' | 'layer/visibility' | 'layer/clipping' | 'appearance/adjustments' | 'appearance/filter' | 'appearance/effect' | 'appearance/blur' | 'appearance/shadow' | 'lifecycle/destroy' | 'lifecycle/duplicate' | 'editor/add' | 'editor/select';
+export declare type Scope = 'text/edit' | 'text/character' | 'fill/change' | 'fill/changeType' | 'stroke/change' | 'shape/change' | 'layer/move' | 'layer/resize' | 'layer/rotate' | 'layer/flip' | 'layer/crop' | 'layer/opacity' | 'layer/blendMode' | 'layer/visibility' | 'layer/clipping' | 'appearance/adjustments' | 'appearance/filter' | 'appearance/effect' | 'appearance/blur' | 'appearance/shadow' | 'appearance/animation' | 'lifecycle/destroy' | 'lifecycle/duplicate' | 'editor/add' | 'editor/select';
 
 /** @public */
 export declare type SettingsBool = 'controlGizmo/showCropHandles' | 'controlGizmo/showCropScaleHandles' | 'controlGizmo/showResizeHandles' | 'controlGizmo/showRotateHandles' | 'controlGizmo/showScaleHandles' | 'doubleClickToCropEnabled' | 'features/singlePageModeEnabled' | 'features/pageCarouselEnabled' | 'mouse/enableScroll' | 'mouse/enableZoom' | 'checkScopesInAPIs' | 'page/dimOutOfPageAreas' | 'page/title/appendPageName' | 'page/title/show' | 'page/title/showOnSinglePage' | 'page/title/showPageTitleTemplate' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'blockAnimations/enabled' | 'showBuildVersion' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning';
@@ -4825,14 +4934,6 @@ export declare interface Vec3 {
     z: number;
 }
 
-/** @public */
-export declare interface Vec4 {
-    x: number;
-    y: number;
-    z: number;
-    w: number;
-}
-
 /**
  * - Top: The blocks get top aligned.
  * - Bottom: The blocks get bottom aligned.