@cesdk/cesdk-js 1.9.0-preview.2 → 1.9.0

package/index.d.ts

@@ -40,6 +40,7 @@ export declare interface Asset {
         uri?: string;
         filename?: string;
         vectorPath?: string;
+        duration?: string;
     } & Record<string, unknown>;
 }
 
@@ -98,6 +99,8 @@ export declare class AssetAPI {
     canManageAssets(sourceId: string): boolean;
 
 
+
+
     /**
      * Apply an asset result to the active scene.
      * The default behavior will instantiate a block and configure it according to the asset's properties.
@@ -106,12 +109,25 @@ export declare class AssetAPI {
      * @param assetResult - A single assetResult of a `findAssets` query.
      */
     apply(sourceId: string, assetResult: AssetResult): Promise<void>;
+    /**
+     * Apply an asset result to the given block.
+     * @param sourceId - The ID of the asset source.
+     * @param assetResult - A single assetResult of a `findAssets` query.
+     * @param block - The block the asset should be applied to.
+     */
+    applyToBlock(sourceId: string, assetResult: AssetResult, block: DesignBlockId): Promise<void>;
     /**
      * The default implementation for applying an asset to the scene.
      * This implementation is used when no `applyAsset` function is provided to `addSource`.
      * @param assetResult - A single assetResult of a `findAssets` query.
      */
     defaultApplyAsset(assetResult: AssetResult): Promise<void>;
+    /**
+     * The default implementation for applying an asset to an existing block.
+     * @param assetResult - A single assetResult of a `findAssets` query.
+     * @param block - The block to apply the asset result to.
+     */
+    defaultApplyAssetToBlock(assetResult: AssetResult, block: DesignBlockId): Promise<void>;
 
 }
 
@@ -143,7 +159,13 @@ export declare interface _AssetElement {
 }
 
 /** @public */
-declare type AssetLibraryEntries = AssetLibraryEntry[] | ((currentAssetLibraryEntries: AssetLibraryEntry[]) => AssetLibraryEntry[]);
+declare type AssetLibraryEntries = AssetLibraryEntry[] | ((currentAssetLibraryEntries: AssetLibraryEntry[], context: {
+    selectedBlocks: {
+        id: DesignBlockId;
+        blockType: DesignBlockType;
+        fillType?: DesignBlockType;
+    }[];
+}) => AssetLibraryEntry[]);
 
 /** @public */
 declare interface AssetLibraryEntry extends AssetLibraryEntryData, AssetLibraryEntryView {
@@ -286,6 +308,7 @@ declare interface AssetResult_2 {
     meta?: {
         uri?: string;
         filename?: string;
+        duration?: string;
     } & Record<string, unknown>;
     /** The locale of the label and tags */
     locale?: string;
@@ -358,6 +381,11 @@ export declare interface AssetSource {
      * You can override this with custom behavior.
      */
     applyAsset?: (asset: AssetResult) => Promise<void>;
+    /**
+     * Apply the given asset result to the given block.
+     * You can override this with custom behavior.
+     */
+    applyAssetToBlock?: (asset: AssetResult, block: DesignBlockId) => Promise<void>;
     /**
      * Adds the given asset to this source. Throws an error if `canManageAssets`
      * is `false`.
@@ -378,6 +406,12 @@ export declare interface AssetSource {
      * @returns true if asset was found and removed, and false otherwise
      */
     removeAsset?(assetId: string): Promise<boolean>;
+    /**
+     * Generates a list of supported mime types for this source.
+     *
+     * @returns a list of the mime types should be supported by this source
+     */
+    getSupportedMimeTypes?(): string[] | undefined;
 }
 
 /**
@@ -392,6 +426,12 @@ declare interface AssetSource_2 {
      * You can override this with custom behavior.
      */
     applyAsset?: (asset: AssetResult_2) => Promise<void>;
+    /**
+     * Apply the given asset result to the given block.
+     * You can override this with custom behavior.
+     */
+    applyAssetToBlock?: (asset: AssetResult_2, block: number) => Promise<void>;
+
     /** Return every available group */
     getGroups?: () => Promise<string[]>;
     /**
@@ -412,6 +452,13 @@ declare interface AssetSource_2 {
         name: string;
         url?: string;
     };
+
+    /**
+     * Generates a list of supported mime types for this source.
+     *
+     * @returns a list of the mime types should be supported by this source
+     */
+    getSupportedMimeTypes?(): string[] | undefined;
 }
 
 /** @public */
@@ -549,6 +596,12 @@ export declare class BlockAPI {
      * @returns An array of block ids.
      */
     findAllSelected(): DesignBlockId[];
+    /**
+     * Subscribe to changes in the current set of selected blocks.
+     * @param callback - This function is called at the end of the engine update if the selection has changed.
+     * @returns A method to unsubscribe.
+     */
+    onSelectionChanged(callback: () => void): () => void;
     /**
      * Confirms that a given set of blocks can be grouped together.
      * @param ids - A non-empty array of block ids.
@@ -1012,6 +1065,29 @@ export declare class BlockAPI {
      * @returns A tuple of channels red, green, blue and alpha in the range of 0 to 1.
      */
     getColorRGBA(id: DesignBlockId, property: string): RGBA;
+    /**
+     * Set a color property of the given design block to the given value.
+     * @param id - The block whose property should be set.
+     * @param property - The name of the property to set.
+     * @param name - The name of the spot color.
+     * @param tint - The tint factor in the range of 0 to 1.
+     * @returns An empty result on success, an error otherwise.
+     */
+    setColorSpot(id: DesignBlockId, property: string, name: string, tint?: number): void;
+    /**
+     * Get the spot color name of a color property of the given design block.
+     * @param id - The block whose property should be queried.
+     * @param property - The name of the property to query.
+     * @returns A result holding the name of the spot color or an error.
+     */
+    getColorSpotName(id: DesignBlockId, property: string): string;
+    /**
+     * Get the spot color tint factor of a color property of the given design block.
+     * @param id - The block whose property should be queried.
+     * @param property - The name of the property to query.
+     * @returns A result holding the tint factor of the spot color or an error.
+     */
+    getColorSpotTint(id: DesignBlockId, property: string): number;
     /**
      * Set an enum property of the given design block to the given value.
      * @param id - The block whose property should be set.
@@ -1916,17 +1992,28 @@ export declare class BlockAPI {
     /**
      * Generate a thumbnail for the given video fill.
      * @param id - The video fill.
-     * @returns A thumbnail encoded as JPEG with a height of 128px.
+     * @param thumbnailHeight - The height of a thumbnail. The width will be calculated from the video aspect ratio.
+     * @returns A thumbnail encoded as JPEG.
      */
-    getVideoFillThumbnail(id: DesignBlockId): Promise<Blob>;
+    getVideoFillThumbnail(id: DesignBlockId, thumbnailHeight: number): Promise<Blob>;
     /**
      * Generate a thumbnail atlas for the given video fill.
      * @param id - The video fill.
      * @param numberOfColumns - The number of columns to generate.
      * @param numberOfRows - The number of rows to generate.
+     * @param thumbnailHeight - The height of a thumbnail. The width will be calculated from the video aspect ratio.
      * @returns A thumbnail atlas of the video as JPEG.
      */
-    getVideoFillThumbnailAtlas(id: DesignBlockId, numberOfColumns: number, numberOfRows: number): Promise<Blob>;
+    getVideoFillThumbnailAtlas(id: DesignBlockId, numberOfColumns: number, numberOfRows: number, thumbnailHeight: number): Promise<Blob>;
+    /**
+     * Generate a thumbnail atlas for the given page.
+     * @param id - The page.
+     * @param numberOfColumns - The number of columns to generate.
+     * @param numberOfRows - The number of rows to generate.
+     * @param thumbnailHeight - The height of a thumbnail. The width will be calculated from the page aspect ratio.
+     * @returns A thumbnail atlas of the composition as JPEG.
+     */
+    getPageThumbnailAtlas(id: DesignBlockId, numberOfColumns: number, numberOfRows: number, thumbnailHeight: number): Promise<Blob>;
 }
 
 /** @public */
@@ -1989,6 +2076,8 @@ declare namespace ConfigTypes {
         Theme,
         Scale,
         PartialImageElement,
+        PartialVideoElement,
+        PartialAudioElement,
         I18n,
         A11y,
         OnUploadCallback,
@@ -2052,19 +2141,19 @@ declare class CreativeEditorSDK {
      * @deprecated Use `loadFromString` instead.
      * @param scene -  A string starting with UBQ1 and containing the encoded scene.
      */
-    load(scene: string): Promise<void>;
+    load(scene: string): Promise<number>;
     /**
      * Load an encoded scene from the provided string.
      * @param scene -  A string starting with UBQ1 and containing the encoded scene.
      * @returns a promise which resolves if the scene was successfully loaded.
      */
-    loadFromString(scene: string): Promise<void>;
+    loadFromString(scene: string): Promise<number>;
     /**
      * Load the scene stored in the file at the given URL.
      * @param url -  The url to fetch to acquire the scene string.
      * @returns a promise which resolves if the scene was successfully loaded.
      */
-    loadFromURL(url: string): Promise<void>;
+    loadFromURL(url: string): Promise<number>;
     /**
      * Save and return a scene as a base64 encoded string.
      *
@@ -2161,6 +2250,7 @@ export declare enum DesignBlockType {
     Page = "//ly.img.ubq/page",
     Image = "//ly.img.ubq/image",
     Video = "//ly.img.ubq/video",
+    VideoFill = "//ly.img.ubq/fill/video",
     Audio = "//ly.img.ubq/audio",
     Text = "//ly.img.ubq/text",
     Sticker = "//ly.img.ubq/sticker",
@@ -2228,6 +2318,28 @@ export declare class EditorAPI {
      * @returns The text cursor's y position in screen space.
      */
     getTextCursorPositionInScreenSpaceY(): number;
+    /**
+     * Create a history which consists of an undo/redo stack for editing operations.
+     * There can be multiple. But only one can be active at a time.
+     * @returns The handle of the created history.
+     */
+    createHistory(): HistoryId;
+    /**
+     * Destroy the given history, throws an error if the handle doesn't refer to a history.
+     * @param history - The history to destroy.
+     */
+    destroyHistory(history: HistoryId): void;
+    /**
+     * Mark the given history as active, throws an error if the handle doesn't refer to a history.
+     * All other histories get cleared from the active state. Undo/redo operations only apply to the active history.
+     * @param history - The history to make active.
+     */
+    setActiveHistory(history: HistoryId): void;
+    /**
+     * Get the handle to the currently active history. If there's none it will be created.
+     * @returns History - The handle of the active history.
+     */
+    getActiveHistory(): HistoryId;
     /**
      * Adds a new history state to the stack, if undoable changes were made.
      */
@@ -2252,6 +2364,13 @@ export declare class EditorAPI {
      * @returns True if a redo step is available.
      */
     canRedo(): boolean;
+    /**
+     * Subscribe to changes to the undo/redo history.
+     *
+     * @param callback - This function is called at the end of the engine update, if the undo/redo history has been changed.
+     * @returns A method to unsubscribe
+     */
+    onHistoryUpdated(callback: () => void): () => void;
     /**
      * Subscribe to changes to the editor settings.
      * @param callback - This function is called at the end of the engine update, if the editor settings have changed.
@@ -2373,6 +2492,34 @@ export declare class EditorAPI {
      * @returns `Allow` if the scope is allowed, `Deny` if it is disallowed, and `Defer` if it is deferred to the block-level.
      */
     getGlobalScope(key: string): 'Allow' | 'Deny' | 'Defer';
+    /**
+     * Queries the names of currently set spot colors previously set with `setSpotColorRGB`.
+     * @returns The names of set spot colors.
+     */
+    findAllSpotColors(): string[];
+    /**
+     * Queries the RGB representation set for a spot color.
+     * If the value of the queried spot color has not been set yet, returns the default RGB representation (of magenta).
+     * The alpha value is always 1.0.
+     * @param name - The name of a spot color.
+     * @returns A result holding a float array of the four color components.
+     */
+    getSpotColorRGBA(name: string): RGBA;
+    /**
+     * Sets the RGB representation of a spot color.
+     * Use this function to both create a new spot color or update an existing spot color.
+     * @param name - The name of a spot color.
+     * @param r - The red color component in the range of 0 to 1.
+     * @param g - The green color component in the range of 0 to 1.
+     * @param b - The blue color component in the range of 0 to 1.
+     */
+    setSpotColorRGB(name: string, r: number, g: number, b: number): void;
+    /**
+     * Removes a spot color from the list of set spot colors.
+     * @param name - The name of a spot color.
+     * @returns An empty result on success, an error otherwise.
+     */
+    removeSpotColor(name: string): void;
 }
 
 declare namespace _EngineConfigTypes {
@@ -2426,6 +2573,13 @@ export declare interface _EngineConfiguration {
      * If not configured the fallback font is used.
      */
     defaultFont?: string;
+    /**
+     * By default the engine tries to create a webgl2 context. If this fails it
+     * falls back to trying to create a webgl1 context. If this configuration
+     * option is set to true, it will no longer try to create a webgl2 context
+     * and always create a webgl1 context.
+     */
+    forceWebGL1?: boolean;
 }
 
 /**
@@ -2525,7 +2679,7 @@ declare type Extensions = {
 /**
  * @public
  */
-export declare type FillType = 'Solid' | 'Gradient';
+export declare type FillType = 'Solid' | 'Gradient' | 'Video';
 
 /** @public */
 declare interface FindAssetsQuery {
@@ -2598,6 +2752,12 @@ declare type Groups = string[];
  */
 declare type HexColorString = string;
 
+/**
+ * A numerical identifier for a history stack
+ * @public
+ */
+export declare type HistoryId = number;
+
 /**
  * I18n Settings
  * Note: this will append keys and not override keys
@@ -2660,11 +2820,11 @@ declare enum NavigationPosition {
 }
 
 /** @public */
-declare type OnUploadCallback = (file: File, onProgress: (progress: number) => void) => Promise<PartialImageElement>;
+declare type OnUploadCallback = (file: File, onProgress: (progress: number) => void) => Promise<PartialImageElement | PartialVideoElement | PartialAudioElement>;
 
 /** @public */
 declare type OnUploadOptions = {
-    supportedMimeTypes: string[];
+    supportedMimeTypes?: string[];
 };
 
 /**
@@ -2708,9 +2868,15 @@ declare enum PanelPosition {
     Right = "right"
 }
 
+/** @public */
+declare type PartialAudioElement = Optional<AudioElement, 'duration'>;
+
 /** @public */
 declare type PartialImageElement = Optional<_ImageElement, 'size'>;
 
+/** @public */
+declare type PartialVideoElement = Optional<VideoElement, 'size' | 'duration'>;
+
 /**
  * - Absolute: Position in absolute design units.
  * - Percent: Position in relation to the block's parent's size in percent, where 1.0 means 100%.
@@ -2771,6 +2937,7 @@ declare interface QueryData {
 
 /** @public */
 export declare interface _RequiredConfiguration extends _EngineConfiguration {
+    initialSceneMode?: SceneMode;
     initialSceneString?: string;
     initialSceneURL?: string;
     initialImageURL?: string;
@@ -2875,7 +3042,7 @@ export declare class SceneAPI {
      * Create a new design scene, along with its own camera.
      * @returns The scene's handle.
      */
-    create(): DesignBlockId;
+    create(sceneLayout?: SceneLayout): DesignBlockId;
     /**
      * Create a new scene in video mode, along with its own camera and page stack.
      * @returns The scene's handle.
@@ -2890,7 +3057,7 @@ export declare class SceneAPI {
      * @param pixelScaleFactor - The displays pixel scale factor.
      * @returns A promise that resolves with the scene ID on success or rejected with an error otherwise.
      */
-    createFromImage(url: string, dpi?: number, pixelScaleFactor?: number): Promise<DesignBlockId>;
+    createFromImage(url: string, dpi?: number, pixelScaleFactor?: number, sceneLayout?: SceneLayout, spacing?: number, spacingInScreenSpace?: boolean): Promise<DesignBlockId>;
     /**
      * Return the currently active scene.
      * @returns The scene or null, if none was created yet.
@@ -2914,6 +3081,11 @@ export declare class SceneAPI {
      * @returns A Promise that resolves once the template was applied or rejects if there was an error.
      */
     applyTemplateFromURL(url: string): Promise<void>;
+    /**
+     * Get the current scene mode.
+     * @returns The current mode of the scene.
+     */
+    getMode(): SceneMode;
     /**
      * Sets the zoom level of the active scene.
      * Only has an effect if the zoom level is not handled by the UI.
@@ -2945,7 +3117,13 @@ export declare class SceneAPI {
      * @returns A method to unsubscribe.
      * @privateRemarks This will currently fire on _all_ changes to camera properties
      */
-    onZoomLevelChanged(callback: (zoomLevel: number) => void): () => void;
+    onZoomLevelChanged(callback: () => void): () => void;
+    /**
+     * Subscribe to changes to the active scene rendered by the engine.
+     * @param callback - This function is called at the end of the engine update, if the active scene has changed.
+     * @returns A method to unsubscribe.
+     */
+    onActiveChanged(callback: () => void): () => void;
     /**
      * Converts all values of the current scene into the given design unit.
      * @param designUnit - The new design unit of the scene
@@ -2958,6 +3136,18 @@ export declare class SceneAPI {
     unstable_getDesignUnit(): DesignUnit;
 }
 
+/**
+ * The scene layout determines how the layout stack should layout its pages.
+ * @public
+ */
+export declare type SceneLayout = 'Free' | 'VerticalStack' | 'HorizontalStack' | 'DepthStack';
+
+/**
+ * The mode of the scene defines how the editor and playback should behave.
+ * @public
+ */
+export declare type SceneMode = 'Design' | 'Video';
+
 /**
  * - Absolute: Size in absolute design units.
  * - Percent: Size in relation to the block's parent's size in percent, where 1.0 means 100%.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cesdk/cesdk-js",
-  "version": "1.9.0-preview.2",
+  "version": "1.9.0",
   "main": "./cesdk.umd.js",
   "types": "./index.d.ts",
   "homepage": "https://www.img.ly",