@cesdk/cesdk-js 1.10.0 → 1.11.0-preview.0

package/index.d.ts

@@ -554,17 +554,13 @@ export declare class BlockAPI {
     /**
      * Exports a design block as a video file of the given mime type.
      * Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.
-     * @param block - The design block to export.
-     * @param timeOffset - The time offset in seconds of the scene's timeline from which the video will start.
-     * @param duration - The duration in seconds of the final video.
+     * @param handle - The design block element to export. Currently, only the scene block is supported.
      * @param mimeType - The mime type of the output video file.
-     * @param resolutionWidth - The target video width in pixel.
-     * @param resolutionHeight - The target video height in pixel.
-     * @param framerate - The target framerate in Hz.
      * @param progressCallback - A callback which reports on the progress of the export. It informs the receiver of the current frame index, which currently gets exported and the total frame count.
+     * @param options - The options for exporting the video
      * @returns A promise that resolves with video blob or is rejected with an error.
      */
-    exportVideo(handle: DesignBlockId, timeOffset: number, duration: number, mimeType: MimeType_2 | undefined, resolutionWidth: number, resolutionHeight: number, framerate: number, progressCallback: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void): Promise<Blob>;
+    exportVideo(handle: DesignBlockId, mimeType: MimeType_2 | undefined, progressCallback: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void, options: VideoExportOptions): Promise<Blob>;
     /**
      * Loads existing blocks from the given string.
      * The blocks are not attached by default and won't be visible until attached to a page or the scene.
@@ -884,7 +880,7 @@ export declare class BlockAPI {
     /**
      * Set a block's mode for its width.
      * @param id - The block to update.
-     * @param mode - The width mode: absolute, percent or auto.
+     * @param mode - The width mode: Absolute, Percent or Auto.
      */
     setWidthMode(id: DesignBlockId, mode: SizeMode): void;
     /**
@@ -896,7 +892,7 @@ export declare class BlockAPI {
     /**
      * Set a block's mode for its height.
      * @param id - The block to update.
-     * @param mode - The height mode: absolute, percent or auto.
+     * @param mode - The height mode: Absolute, Percent or Auto.
      */
     setHeightMode(id: DesignBlockId, mode: SizeMode): void;
     /**
@@ -1184,14 +1180,14 @@ export declare class BlockAPI {
      * @param property - The name of the property to set.
      * @param value - The enum value as string.
      */
-    setEnum(id: DesignBlockId, property: string, value: string): void;
+    setEnum<T extends string = string>(id: DesignBlockId, property: string, value: T): void;
     /**
      * Get the value of an enum 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 The value as string.
      */
-    getEnum(id: DesignBlockId, property: string): string;
+    getEnum<T extends string = string>(id: DesignBlockId, property: string): T;
     /**
      * Query if the given block has crop properties.
      * @param id - The block to query.
@@ -1723,6 +1719,69 @@ export declare class BlockAPI {
      * @returns The drop shadow's clipping.
      */
     getDropShadowClip(id: DesignBlockId): boolean;
+    /**
+     * Inserts the given text into the selected range of the text block.
+     * @param block - The text block into which to insert the given text.
+     * @param text - The text which should replace the selected range in the block.
+     * @param from - The start index of the UTF-16 range that should be replaced.
+     * If the value is negative, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme that should be replaced by the inserted text.
+     *   If `from` and `to` are negative, a this will fall back to the end of the entire text range, so the entire text will be replaced.
+     *   If `to` is negative but `from` is greater than or equal to 0, the text will be inserted at the index defined by `from`.
+     */
+    replaceText(id: DesignBlockId, text: string, from?: number, to?: number): void;
+    /**
+     * Removes selected range of text of the given text block.
+     * @param block - The text block from which the selected text should be removed.
+     * @param from - The start index of the UTF-16 range that should be removed.
+     * If the value is negative, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme that should be removed.
+     * If the value is negative, this will fall back to the end of the entire text range.
+     */
+    removeText(id: DesignBlockId, from?: number, to?: number): void;
+    /**
+     * Changes the color of the text in the selected range to the given color.
+     * @param block - The text block whose color should be changed.
+     * @param color - The new color of the selected text range.
+     * @param from - The start index of the UTF-16 range whose color should be changed.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose color should be changed.
+     *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
+     */
+    setTextColor(id: DesignBlockId, color: RGBAColor | SpotColor, from?: number, to?: number): void;
+    /**
+     * Returns the ordered unique list of colors of the text in the selected range.
+     * @param block - The text block whose colors should be returned.
+     * @param from - The start index of the UTF-16 range whose colors should be returned.
+     * If the value is negative, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose colors should be returned.
+     * If the value is negative, this will fall back to the end of the entire text range.
+     */
+    getTextColors(id: DesignBlockId, from?: number, to?: number): Array<RGBAColor | SpotColor>;
+    /**
+     * Returns the ordered unique list of font weights of the text in the selected range.
+     * @param block - The text block whose font weights should be returned.
+     * @param from - The start index of the UTF-16 range whose font weights should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose font weights should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
+     */
+    getTextFontWeights(id: DesignBlockId, from?: number, to?: number): FontWeight[];
+    /**
+     * Returns the ordered unique list of font styles of the text in the selected range.
+     * @param block - The text block whose font styles should be returned.
+     * @param from - The start index of the UTF-16 range whose font weights should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose font styles should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
+     */
+    getTextFontStyles(id: DesignBlockId, from?: number, to?: number): FontStyle[];
     /**
      * Query if the given block has fill color properties.
      * @param id - The block to query.
@@ -2274,16 +2333,16 @@ export declare interface CMYKColor {
  * The RGB and CMYK components must all be specified in the range [0-1].
  * @public
  */
-declare type Color = HexColorString | RGBColor | RGBAColor | SpotColor;
+declare type Color_2 = HexColorString | RGBColor | RGBAColor | SpotColor;
 
 /** @public */
 declare type ColorDefinition = Preset & {
-    value: Color;
+    value: Color_2;
 };
 
 /** @public */
 declare type ColorPaletteDefinition = Preset & {
-    entries: Color[];
+    entries: Color_2[];
 };
 
 declare namespace ConfigTypes {
@@ -2313,7 +2372,18 @@ export { ConfigTypes }
  * optional and what mandatory. This is Configuration, but `ui` is recursively
  * optional, and all other props are non-recursively optional
  */
-export declare type Configuration = Partial<_RequiredConfiguration>;
+export declare type Configuration = Partial<_RequiredConfiguration> & OldConfiguration;
+
+/**
+ * A public interface for controlling several configuration options of the
+ * Creative Editor SDK
+ *
+ * @public
+ */
+export declare class ConfigurationAPI {
+    #private;
+    setRole(role: RoleString): void;
+}
 
 /**
  * - Crop: Manual crop.
@@ -2338,7 +2408,7 @@ declare class CreativeEditorSDK {
     /**
      * Convenience function that registers a set of asset sources containing our
      * example assets. These are
-     * - `'ly.img.image'` - Sample images
+     *
      * - `'ly.img.sticker'` - Various stickers
      * - `'ly.img.vectorpath'` - Shapes and arrows
      * - `'ly.img.filter.lut'` - LUT effects of various kinds.
@@ -2357,22 +2427,20 @@ declare class CreativeEditorSDK {
         excludeAssetSourceIds?: DefaultAssetSourceId[];
     }): Promise<void>;
     /**
-     * Convenience function that registers a set of asset sources containing our
-     * example assets. These are
-     * - `'ly.img.image'` - Sample images
-     * - `'ly.img.sticker'` - Various stickers
-     * - `'ly.img.vectorpath'` - Shapes and arrows
-     * - `'ly.img.filter.lut'` - LUT effects of various kinds.
-     * - `'ly.img.filter.duotone'` - LUT effects of various kinds.
+     * Convenience function that registers a set of demo asset sources containing our
+     * example assets. These are not to meant to be used in your production code.
      *
-     * These assets are parsed from the IMG.LY CDN at \{\{base_url\}\}/<id>/content.json, where
-     * `base_url` defaults to 'https://cdn.img.ly/assets/v1'.
-     * Each source is created via `addLocalSource` and populated with the parsed assets. To modify the available
-     * assets, you may either exclude certain IDs via `excludeAssetSourceIds` or alter the sources after creation.
+     * These are
+     *
+     * - `'ly.img.image'` - Sample images
+     * - `'ly.img.image.upload'` - Demo source to upload image assets
+     * - `'ly.img.audio'` - Sample audios
+     * - `'ly.img.audio.upload'` - Demo source to upload audio assets
+     * - `'ly.img.video'` - Sample videos
+     * - `'ly.img.video.upload'` - Demo source to upload video assets
      *
-     * @param baseURL - The source of the asset definitions, must be absolute. Defaults to `'https://cdn.img.ly/assets/v1'`.
      * @param excludeAssetSourceIds - A list of IDs, that will be ignored during load.
-     * @param sceneMode - if 'Video' video specific demo asset sources will be loaded as well.
+     * @param sceneMode - if 'Video' video specific demo asset sources will be loaded as well. Parsed from global configuration if not set.
      */
     addDemoAssetSources({ excludeAssetSourceIds, sceneMode }?: {
         baseURL?: string;
@@ -2495,7 +2563,7 @@ export declare class CreativeEngine {
      * @param config - An optional configuration object.
      * @returns An engine instance.
      */
-    static init<C extends Partial<_EngineConfiguration>>(config?: C): Promise<CreativeEngine & (C extends {
+    static init<C extends Partial<_EngineConfiguration> & _OldEngineConfiguration>(config?: C): Promise<CreativeEngine & (C extends {
         readonly canvas: any;
     } ? {
         readonly element: undefined;
@@ -2533,7 +2601,7 @@ export declare class CreativeEngine {
      * - `'ly.img.image.upload'` - Demo source to upload image assets
      * - `'ly.img.audio'` - Sample audios
      * - `'ly.img.audio.upload'` - Demo source to upload audio assets
-     * - `'ly.img.video'` - Sample audios
+     * - `'ly.img.video'` - Sample videos
      * - `'ly.img.video.upload'` - Demo source to upload video assets
      *
      * @param excludeAssetSourceIds - A list of IDs, that will be ignored during load.
@@ -2599,8 +2667,11 @@ export declare enum DesignBlockType {
     Group = "//ly.img.ubq/group"
 }
 
-/** @public */
-export declare type DesignUnit = 'mm' | 'px' | 'in';
+/**
+ * The scene layout determines how the layout stack should layout its pages.
+ * @public
+ */
+export declare type DesignUnit = 'Pixel' | 'Millimeter' | 'Inch';
 
 /** @public */
 declare interface DockGroup {
@@ -2620,7 +2691,7 @@ export declare class EditorAPI {
      * @param callback - This function is called at the end of the engine update, if the editor state has changed.
      * @returns A method to unsubscribe.
      */
-    onStateChanged(callback: () => void): () => void;
+    onStateChanged: (callback: () => void) => (() => void);
     /**
      * Set the edit mode of the editor.
      * An edit mode defines what type of content can currently be edited by the user.
@@ -2706,13 +2777,13 @@ export declare class EditorAPI {
      * @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;
+    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.
      * @returns A method to unsubscribe.
      */
-    onSettingsChanged(callback: () => void): () => void;
+    onSettingsChanged: (callback: () => void) => (() => void);
     /**
      * Set a boolean setting.
      * @param keypath - The settings keypath, e.g. `doubleClickToCropEnabled`
@@ -2871,7 +2942,7 @@ export declare class EditorAPI {
 declare namespace _EngineConfigTypes {
     export {
         HexColorString,
-        Color,
+        Color_2 as Color,
         AssetSources,
         AssetSource_2 as AssetSource,
         AssetResult_2 as AssetResult,
@@ -2899,15 +2970,15 @@ export { _EngineConfigTypes }
 export declare interface _EngineConfiguration {
     baseURL: string;
     license?: string;
-    role: RoleString;
-    featureFlags?: Record<string, string | boolean>;
+    featureFlags?: {
+        [flag: string]: boolean | string;
+    };
     /**
      * @deprecated Extensions have been superseded by AssetSources and should no longer be used.
      */
     extensions: _EngineConfigTypes.Extensions;
     core: _EngineConfigTypes.Core;
     scene: _EngineConfigTypes.Scene;
-    page: _EngineConfigTypes.Page;
     assetSources: _EngineConfigTypes.AssetSources;
     presets: _EngineConfigTypes.Presets;
     variables: _EngineConfigTypes.Variables;
@@ -2991,7 +3062,7 @@ export declare class EventAPI {
      * @param callback - The event callback. Events are bundled and sent at the end of each engine update.
      * @returns A method to unsubscribe.
      */
-    subscribe(blocks: DesignBlockId[], callback: (events: BlockEvent[]) => void): () => void;
+    subscribe: (blocks: DesignBlockId[], callback: (events: BlockEvent[]) => void) => (() => void);
 }
 
 /** @public */
@@ -3187,6 +3258,37 @@ declare enum NavigationPosition {
     Bottom = "bottom"
 }
 
+/**
+ * Contains configuration keys that have been removed from the actual
+ * configuration, but are still supported publicly
+ * @public
+ */
+export declare interface OldConfiguration extends _OldEngineConfiguration {
+}
+
+/**
+ * Contains configuration keys that have been removed from the actual
+ * configuration, but are still supported publicly
+ * @public
+ */
+export declare interface _OldEngineConfiguration {
+    /**
+     * @deprecated This config key has been removed.
+     * You can configure a role via `setSettingEnum('role', role)` in the
+     * EditorAPI.
+     */
+    role?: RoleString;
+    /**
+     * @deprecated This config key has been removed completely.
+     * The settings that were configured here can be set via the
+     * following EditorAPI settings:
+     * - `setSettingBool('page/title/show', show)`
+     * - `setSettingString('page/title/fontFileUri', uri)`
+     * - `setSettingBool('page/title/dimOutOfPageAreas', dim)`
+     */
+    page?: Page;
+}
+
 /** @public */
 declare type OnUploadCallback = (file: File, onProgress: (progress: number) => void) => Promise<AssetDefinition>;
 
@@ -3201,7 +3303,15 @@ declare type OnUploadOptions = {
  */
 export declare type Optional<T, K extends keyof T> = Omit<T, K> & Partial<T>;
 
-/** @public */
+/**
+ * @deprecated This type definition has been removed
+ * The settings that were configured here can be set via the
+ * following EditorAPI settings:
+ * - `setSettingBool('page/title/show', show)`
+ * - `setSettingString('page/title/fontFileUri', uri)`
+ * - `setSettingBool('page/title/dimOutOfPageAreas', dim)`
+ * @public
+ */
 declare type Page = {
     title: {
         /**
@@ -3224,7 +3334,7 @@ declare type Page = {
 declare type PageFormatDefinition = Preset & {
     width: number;
     height: number;
-    unit: DesignUnit;
+    unit: 'px' | 'mm' | 'in';
     fixedOrientation?: boolean;
 };
 
@@ -3445,11 +3555,19 @@ export declare class SceneAPI {
      * Fetching the image may take an arbitrary amount of time, so the scene isn't immediately
      * available.
      * @param url - The image URL.
-     * @param dpi - The scenes DPI.
-     * @param pixelScaleFactor - The displays pixel scale factor.
+     * @param dpi - The scene's DPI.
+     * @param pixelScaleFactor - The display's 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, sceneLayout?: SceneLayout, spacing?: number, spacingInScreenSpace?: boolean): Promise<DesignBlockId>;
+    /**
+     * Loads the given video and creates a scene with a single page showing the video.
+     * Fetching the video may take an arbitrary amount of time, so the scene isn't immediately
+     * available.
+     * @param url - The video URL.
+     * @returns A promise that resolves with the scene ID on success or rejected with an error otherwise.
+     */
+    createFromVideo(url: string): Promise<DesignBlockId>;
     /**
      * Return the currently active scene.
      * @returns The scene or null, if none was created yet.
@@ -3478,6 +3596,16 @@ export declare class SceneAPI {
      * @returns The current mode of the scene.
      */
     getMode(): SceneMode;
+    /**
+     * Converts all values of the current scene into the given design unit.
+     * @param designUnit - The new design unit of the scene
+     */
+    setDesignUnit(designUnit: DesignUnit): void;
+    /**
+     * Returns the design unit of the current scene.
+     * @returns The current design unit.
+     */
+    getDesignUnit(): DesignUnit;
     /**
      * Get the sorted list of pages in the scene.
      * @returns The sorted list of pages in the scene.
@@ -3555,23 +3683,13 @@ export declare class SceneAPI {
      * @returns A method to unsubscribe.
      * @privateRemarks This will currently fire on _all_ changes to camera properties
      */
-    onZoomLevelChanged(callback: () => 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
-     */
-    unstable_setDesignUnit(designUnit: DesignUnit): void;
-    /**
-     * Returns the design unit of the current scene.
-     * @returns The current design unit.
-     */
-    unstable_getDesignUnit(): DesignUnit;
+    onActiveChanged: (callback: () => void) => (() => void);
 }
 
 /**
@@ -3628,8 +3746,10 @@ declare type Source<T> = (handler: Handler<T>) => UnsubscribeFn;
 /** @public */
 export declare interface SpotColor {
     name: string;
-    rgbApproximation: RGBAColor;
-    cmykApproximation: CMYKColor;
+}
+
+declare interface SpotColorLookup {
+    getSpotColorRGBA(name: string): [r: number, g: number, b: number, a: number];
 }
 
 /** @public */
@@ -3940,12 +4060,55 @@ declare interface Vec2 {
     y: number;
 }
 
-/** @public */
-declare interface Vec3 {
-    x: number;
-    y: number;
-    z: number;
-}
+/**
+ * @public
+ */
+declare type VideoExportOptions = {
+    /**
+     * Determines the encoder feature set and in turn the quality, size and speed of the encoding process.
+     *
+     * @defaultValue 77 (Main)
+     */
+    h264Profile?: number;
+    /**
+     * Controls the H.264 encoding level. This relates to parameters used by the encoder such as bit rate,
+     * timings and motion vectors. Defined by the spec are levels 1.0 up to 6.2. To arrive at an integer value,
+     * the level is multiplied by ten. E.g. to get level 5.2, pass a value of 52.
+     *
+     * @defaultValue 52
+     */
+    h264Level?: number;
+    /**
+     * The time offset in seconds of the scene's timeline from which the video will start.
+     *
+     * @defaultValue 0
+     */
+    timeOffset?: number;
+    /**
+     * The duration in seconds of the final video.
+     *
+     * @defaultValue The duration of the scene.
+     */
+    duration?: number;
+    /**
+     * The target framerate of the exported video in Hz.
+     *
+     * @defaultValue 30
+     */
+    framerate?: number;
+    /**
+     * An optional target width used in conjunction with target height.
+     * If used, the block will be rendered large enough, that it fills the target
+     * size entirely while maintaining its aspect ratio.
+     */
+    targetWidth?: number;
+    /**
+     * An optional target height used in conjunction with target width.
+     * If used, the block will be rendered large enough, that it fills the target
+     * size entirely while maintaining its aspect ratio.
+     */
+    targetHeight?: number;
+};
 
 /** @public */
 declare enum ViewStyle {

package/package.json

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